Access groups

Access groups enable granular access control over sources and integrations in the knowledge base using the Attribute-Based Access Control (ABAC) model. Instead of assigning permissions to individual users, you assign special attributes — access groups — to source documents. Access to a document’s information is granted only to the groups assigned to it. This means you can restrict access based on, for example, an employee’s department, a client’s subscription plan or any other attribute.

caution

Groups only restrict access to sources for API requests for chunk retrieval and response generation. In the UI, any user can access any source.

Concepts

• If a source has no access group assigned, it is considered public. Such a source is available to all API requests, regardless of the access groups provided.
• If a source has at least one access group assigned, it is available only to API requests that specify at least one of its assigned groups.
• Sources uploaded via an integration (e.g. Confluence pages) automatically inherit the access groups assigned to that integration.
• An access group can be assigned to sources and integrations across multiple knowledge base projects. An access group name must be unique within the account.

Access logic when requesting chunks:

• If a list of access groups is provided in the request, chunks will be retrieved from all public sources and from restricted sources that match at least one of the provided groups.
• If no access groups are specified in the request (the parameter is missing or contains an empty list), only public sources will be searched.

Example

Let’s assume sources A, B and C are assigned the following access groups:

Source	Access groups
A	confidential internal_docs
B	internal_docs
C	—

If a response generation request to the knowledge base includes the access groups confidential and finance, only data from sources A and C will be used for the response.

Manage access groups

Access groups are managed via the API.

In the UI, you can only view access groups in your account (requires KHUB_OWNER or KHUB_ADMIN role). Assigning access groups to sources and integrations in the UI is not supported.

Assign access groups

When adding a source or creating an integration, specify the list of access groups in the accessControlAttributes field. If a specified group name doesn’t exist, it will be created automatically.

caution

You won’t be able to change the access groups assigned to a source later.

Request examples:

• Add a source with access groups.

  curl \
  --header 'Authorization: Bearer <your_API_key>' \
  --header 'multipart/form-data' \
  --form 'file=@"/path/to/your/document.pdf"' \
  --form 'accessControlAttributes="internal_docs,department_hr' \
  https://data-agent.tovie.ai/api/knowledge-hub/sources/files

• Add an integration with access groups.

  curl \
  --header 'Authorization: Bearer <your_API_key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Customer service",
    "autoSync": true,
    "syncIntervalMinutes": 30,
    "settings": {
      "type": "confluence",
      "space": "Клиентский сервис",
      "token": "aaaBBBcccDDDeeeFFFgggHHHH",
      "baseUrl": "https://confluence.example.com"
    },
    "accessControlAttributes": ["customer_service"]
  }' \
  https://data-agent.tovie.ai/api/knowledge-hub/integrations

Querying based on access groups

To retrieve data from restricted sources, include the accessControlAttributes parameter in your request. This parameter is supported in all requests for chunk retrieval and response generation:

• POST /retrieve
• POST /query
• POST /async/query
• POST /chat/{chatId}/retrieve
• POST /chat/{chatId}/query
• POST /async/chat/{chatId}/query

The following example shows a query where the response is based on public sources and those available to the internal_docs group:

curl \
--header 'Authorization: Bearer <your_API_key>' \
--header 'Content-Type: application/json' \
--data '{
    "query": "vacation policy",
    "accessSettings": {
        "accessControlAttributes": ["internal_docs"]
    }
}' \
https://data-agent.tovie.ai/api/knowledge-hub/query

Access groups based on Confluence restrictions

For Confluence integrations, you can synchronise access restrictions by automatically assigning access groups to each source based on the original page’s viewing rights. For more information, see Synchronise Access Restrictions.

You can specify Confluence user data in chunk retrieval or response generation requests. In this case, the list of access groups is generated automatically based on the user’s rights in Confluence.

The request can include both Confluence user data and a list of access groups in the accessControlAttributes parameter. In this case, the list of access groups based on user rights is merged with the list from accessControlAttributes.

Example of a combined query:

{
    "query": "vacation rules",
    "accessSettings": {
        "accessControlAttributes": ["internal_docs"],
        "integrationId": 12345,
        "externalUserId": "ff10100bcde200ab",
    }
}

The response will be based on the following sources:

1. Confluence pages that the user can personally access (the user-ff10100bcde200ab access group).
2. Confluence pages accessible to any group the user belongs to (for example, the group-department_hr access group).
3. Knowledge base sources that are assigned the internal_docs access group.
4. Public sources.

info

The endpoints, request parameters, response formats, and potential errors are described in detail in the API specification.