Skip to main content

Groups & Resource ACL

Starting from v1.8.0 (Enterprise tier), RAG-DocBot supports group-based access control on connectors and integrations. Access is enforced at retrieval time — users only see chunks that belong to their groups.

Enterprise only

Groups & Resource ACL require an Enterprise license. On FREE and PRO plans, only the built-in everyone group is visible and all chunks are accessible to all authenticated users. The admin bypass applies on all tiers.

Concepts​

ConceptDescription
GroupA named set of users. The built-in everyone group is seeded automatically on first boot and cannot be deleted.
ACLA list of group names attached to a connector or integration. Only users who belong to at least one listed group (or the everyone group, if in the list) can retrieve chunks from that source.
Admin bypassUsers with the admin role bypass all ACL checks and can retrieve from any source regardless of group membership.
No re-embeddingUpdating a connector or integration's ACL updates existing chunk metadata in Qdrant in place — no re-indexing or re-embedding is required.

Managing Groups​

Create a group​

curl -s -X POST http://localhost:8000/api/auth/groups \
  -H "Authorization: Bearer <ADMIN_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"name": "legal-team"}'

List groups​

curl -s http://localhost:8000/api/auth/groups \
  -H "Authorization: Bearer <ADMIN_ACCESS_TOKEN>"

Delete a group​

curl -s -X DELETE http://localhost:8000/api/auth/groups/legal-team \
  -H "Authorization: Bearer <ADMIN_ACCESS_TOKEN>"

The everyone group cannot be deleted.

Assigning Users to Groups​

View a user's current groups​

curl -s http://localhost:8000/api/auth/users/alice/groups \
  -H "Authorization: Bearer <ADMIN_ACCESS_TOKEN>"

Set a user's groups (full replacement)​

curl -s -X PUT http://localhost:8000/api/auth/users/alice/groups \
  -H "Authorization: Bearer <ADMIN_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"groups": ["legal-team", "everyone"]}'

The groups claim in the user's JWT tokens is updated automatically on the next token refresh.

Setting ACL on a Connector​

View the current ACL​

curl -s http://localhost:8000/api/connectors/<CONNECTOR_ID>/acl \
  -H "Authorization: Bearer <ADMIN_ACCESS_TOKEN>"

Update the ACL​

curl -s -X PUT http://localhost:8000/api/connectors/<CONNECTOR_ID>/acl \
  -H "Authorization: Bearer <ADMIN_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"acl_groups": ["legal-team", "compliance-team"]}'

Setting acl_groups to an empty list ([]) makes the connector's chunks visible to all authenticated users.

This PUT immediately updates the acl_groups payload field on all existing chunks in Qdrant — no re-embedding is required.

Setting ACL on an Integration​

The same endpoints and behaviour apply to integrations:

# View
curl -s http://localhost:8000/api/integrations/<INTEGRATION_ID>/acl \
  -H "Authorization: Bearer <ADMIN_ACCESS_TOKEN>"

# Update
curl -s -X PUT http://localhost:8000/api/integrations/<INTEGRATION_ID>/acl \
  -H "Authorization: Bearer <ADMIN_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"acl_groups": ["engineering"]}'

ACL Endpoints Reference​

EndpointDescription
GET /api/auth/groupsList all groups
POST /api/auth/groupsCreate a group
PATCH /api/auth/groups/{name}Rename a group
DELETE /api/auth/groups/{name}Delete a group
GET /api/auth/users/{username}/groupsGet a user's group assignments
PUT /api/auth/users/{username}/groupsReplace a user's group assignments
GET /api/connectors/{id}/aclGet a connector's ACL
PUT /api/connectors/{id}/aclUpdate a connector's ACL (also updates existing chunks)
GET /api/integrations/{id}/aclGet an integration's ACL
PUT /api/integrations/{id}/aclUpdate an integration's ACL (also updates existing chunks)

How ACL is Enforced at Retrieval Time​

Every indexed chunk carries an acl_groups payload field. At query time, the retrieval pipeline injects a Qdrant payload filter:

  • If the user is an admin → no ACL filter applied (all chunks visible).
  • Otherwise → only chunks where acl_groups is empty or contains at least one group the user belongs to are returned.

This filtering happens inside the vector database and has no impact on embedding or re-indexing workflows.

OIDC Group Sync​

When a user logs in via OIDC for the first time, their group membership can be seeded automatically from IdP claims. See the SSO / OIDC guide for details on the OIDC_<NAME>_ADMIN_GROUPS setting and first-login provisioning behaviour.