> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognee.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Permissions & Access Control

> Dataset isolation, roles, tenants, and user management in Cognee Cloud

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](/core-concepts/multi-user-mode/permissions-system/overview).

## 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`):

| Endpoint                                  | Description                        |
| ----------------------------------------- | ---------------------------------- |
| `POST /api/v1/tenants`                    | Create a new tenant                |
| `DELETE /api/v1/tenants`                  | Remove a tenant                    |
| `GET /api/v1/tenants/current`             | Get current tenant details         |
| `GET /api/v1/tenants/current/service-url` | Get the service URL for the tenant |
| `POST /api/v1/tenants/users`              | Assign a user to a tenant          |
| `DELETE /api/v1/tenants/users`            | Remove a user from a tenant        |

## Tenant selection and membership

| Endpoint                                            | Description                                    |
| --------------------------------------------------- | ---------------------------------------------- |
| `POST /api/v1/permissions/tenants/select`           | Set the active tenant                          |
| `GET /api/v1/permissions/tenants/me`                | List tenants the authenticated user belongs to |
| `GET /api/v1/permissions/tenants/{tenant_id}/users` | List users in a tenant                         |

## Roles

Roles define what actions a user can perform within a tenant.

| Endpoint                                                            | Description                     |
| ------------------------------------------------------------------- | ------------------------------- |
| `POST /api/v1/permissions/roles`                                    | Create a new role               |
| `POST /api/v1/permissions/users/{user_id}/roles`                    | Assign a role to a user         |
| `GET /api/v1/permissions/tenants/{tenant_id}/roles`                 | List roles in a tenant          |
| `GET /api/v1/permissions/tenants/{tenant_id}/roles/{role_id}/users` | List 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`.

```bash theme={null}
# 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](/cognee-cloud/connections/managing-connections) 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.

<Info>
  For a complete walkthrough of permission patterns, see [Permission Snippets](/guides/permission-snippets) and the [Cognee Permissions System](/core-concepts/multi-user-mode/permissions-system/overview).
</Info>