Skip to main content
Cognee Cloud enforces access control at the dataset level. Each dataset gets its own Kuzu graph database and LanceDB vector store, ensuring complete data isolation. For the full permissions system documentation, see Cognee Permissions System.

​
Dataset isolation

  • Each dataset maintains separate storage namespaces.
  • Search queries only return results from datasets the user has access to.
  • Scoped search (single dataset) and combined search (across accessible datasets) are both supported.

​
Tenant management

Tenants group users and resources. Each Cognee Cloud workspace operates as a tenant. Platform API (api.aws.cognee.ai):
EndpointDescription
POST /api/v1/tenantsCreate a new tenant
DELETE /api/v1/tenantsRemove a tenant
GET /api/v1/tenants/currentGet current tenant details
GET /api/v1/tenants/current/service-urlGet the service URL for the tenant
POST /api/v1/tenants/usersAssign a user to a tenant
DELETE /api/v1/tenants/usersRemove a user from a tenant

​
Tenant selection and membership

EndpointDescription
POST /api/v1/permissions/tenants/selectSet the active tenant
GET /api/v1/permissions/tenants/meList tenants the authenticated user belongs to
GET /api/v1/permissions/tenants/{tenant_id}/usersList users in a tenant

​
Roles

Roles define what actions a user can perform within a tenant.
EndpointDescription
POST /api/v1/permissions/rolesCreate a new role
POST /api/v1/permissions/users/{user_id}/rolesAssign a role to a user
GET /api/v1/permissions/tenants/{tenant_id}/rolesList roles in a tenant
GET /api/v1/permissions/tenants/{tenant_id}/roles/{role_id}/usersList users with a specific role
GET /api/v1/permissions/tenants/{tenant_id}/roles/users/{user_id}Get roles for a specific user

​
Dataset permissions

Grant access to datasets for specific users or agents. POST /api/v1/permissions/datasets/{principal_id} — Grant dataset permissions to a principal. The principal_id is the UUID of any entity that can hold permissions — this includes both users and agents. The same endpoint is used regardless of whether you are granting access to a human user or to an agent service account. The permission_name query parameter controls the access level: read, write, or delete. 
# Grant read access to a user
curl -X POST "https://your-tenant.aws.cognee.ai/api/v1/permissions/datasets/{user_id}?permission_name=read" \
  -H "X-Api-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '["dataset-uuid-1", "dataset-uuid-2"]'

# Grant read access to an agent (same endpoint, different principal_id)
curl -X POST "https://your-tenant.aws.cognee.ai/api/v1/permissions/datasets/{agent_id}?permission_name=read" \
  -H "X-Api-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '["dataset-uuid-1"]'
This is the same mechanism used by the Connections UI when you share a dataset with an agent.

​
Roles vs. direct permissions

Roles and direct dataset permissions work together:
  • Roles define a reusable set of capabilities within a tenant (e.g., “viewer”, “editor”). Assign a role to a user via POST /api/v1/permissions/users/{user_id}/roles, and that user inherits the role’s permissions across the tenant.
  • Direct dataset permissions grant access to specific datasets for a specific principal. Use the datasets/{principal_id} endpoint above to give a user or agent access to individual datasets, independent of their role.
Both mechanisms can be combined: a user can have a tenant-level role and additional per-dataset grants.
For a complete walkthrough of permission patterns, see Permission Snippets and the Cognee Permissions System.