Guide · Agent skill
How to use the Users, permissions and multi-tenancy agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The cognee-permissions skill teaches an AI agent how cognee controls who can see and change stored datasets. It is for developers building multi-user or multi-tenant applications on cognee, and for engineers chasing PermissionDeniedError or missing-dataset errors. After reading this guide you will know how to install the skill, how to ask for the right work in plain language, and what to check when access control misbehaves.
Users, permissions and multi-tenancytopoteretes/cognee · Apache-2.0 Download the skill Quick start
- 1Install the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings, Capabilities, Skills in the Claude apps.
- 2Confirm your cognee setup. Make sure the cognee Python SDK is installed and that you can reach a cognee server or SDK environment for user creation and login.
- 3Ask for the task in plain language. Describe the users, tenants, roles or datasets involved and the permission you need, such as read or share.
- 4Create users and act as them. Let the agent create users and pass user= to SDK calls, or log in over HTTP to get a bearer token or API key.
- 5Share by dataset id. Grant read, write, delete or share to a user, role or tenant using the dataset's UUID, and have the recipient query with that id.
- 6Debug errors and check access mode. If you hit PermissionDeniedError or a missing dataset, ask the agent to check ids, active tenant and whether ENABLE_BACKEND_ACCESS_CONTROL is on.
What the skill makes the agent do
Every cognee dataset has an owner, and each operation on it is checked against a grant: a principal (a user, role or tenant) holding one of four permissions, read, write, delete or share, on that dataset. With access control on, which is the default, each user and dataset pair also gets its own graph and vector databases.
With the skill installed, the agent knows these rules and can create users, organise them into tenants (organisations) and roles, share datasets with grants, act as a specific user in SDK calls or over the HTTP API, explain where permissions are enforced, and help you debug permission errors.
How to install the cognee-permissions skill
Download the ZIP from the skill's page in this directory and unzip it. The skill is a single file, SKILL.md. Put the unzipped folder in one of two places: ~/.claude/skills/ for all your projects, or .claude/skills/ inside a specific project.
If you use the Claude apps instead, upload the ZIP under Settings, then Capabilities, then Skills. The skill is licensed under Apache-2.0.
- Personal install: ~/.claude/skills/ (available in every project)
- Project install: .claude/skills/ inside your project folder
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
What you need before you start
The skill assumes you already have the cognee Python SDK installed, and access to a cognee server or SDK environment where you can create users and log in. Without that, the agent can explain the model but cannot run user creation or login for you.
Four environment variables are optional and matter for access control: ENABLE_BACKEND_ACCESS_CONTROL, REQUIRE_AUTHENTICATION, DEFAULT_USER_EMAIL and DEFAULT_USER_PASSWORD.
- cognee Python SDK installed
- Access to a cognee server or SDK environment for user creation and login
- Optional: ENABLE_BACKEND_ACCESS_CONTROL, REQUIRE_AUTHENTICATION, DEFAULT_USER_EMAIL, DEFAULT_USER_PASSWORD
How to trigger the skill with natural requests
You do not need a special command. Describe the task and the agent will load the skill when your request matches its scope: creating users, tenants or roles, sharing datasets with read, write, delete or share grants, acting as a user in the SDK or over HTTP, switching access control on or off, or debugging PermissionDeniedError or missing datasets.
Be specific about the principal and the dataset. Name the users, say which permission you want, and give the dataset id if you have it.
- "Create two users, alice and bob, and store Alice's notes in a dataset she owns."
- "Give Bob read access to Alice's dataset by its id."
- "Why does my recall call raise PermissionDeniedError when I pass a dataset id?"
- "Set up a tenant called Acme and add Bob to a Researcher role."
Act as a specific user in the SDK
Without a user argument, SDK calls run as the default user, default_user@example.com, or whatever DEFAULT_USER_EMAIL is set to. To act as someone else, create or load that user and pass it as user=. remember, recall, search, forget, improve and the dataset helpers all accept user=.
Share datasets by id rather than by name. Bob cannot address Alice's dataset by name, because names only resolve among the caller's own datasets.
import cognee
from cognee.modules.users.methods import create_user, get_user
alice = await create_user("alice@example.com", "password")
res = await cognee.remember("Alice's notes", dataset_name="alice_notes", user=alice)
await cognee.recall("What are the notes about?", user=alice, datasets=["alice_notes"])Share a dataset with read, write, delete or share grants
The caller must hold share on the dataset, and the grant is made by dataset id. The principal can be a user, a role or a tenant. The permission argument is one of read, write, delete or share.
Once granted, the other user passes the dataset id as a UUID to recall.
- Grant: authorized_give_permission_on_datasets(principal_id, [dataset_ids], permission, owner_id)
- Revoke: authorized_revoke_permission_on_datasets, with the same kind of arguments
await authorized_give_permission_on_datasets(bob.id, [UUID(res.dataset_id)], "read", alice.id)
await cognee.recall("...", user=bob, dataset_ids=[UUID(res.dataset_id)])Organise users into tenants and roles
A user works inside one active tenant, set with select_tenant. Passing None means the personal space. Datasets are created in the active tenant. Members of a role or tenant receive its grants.
The granter can only share datasets in their current active tenant. Create a dataset while the right tenant is active if you want it shared inside that tenant. After changing the active tenant, reload the user with get_user, because an old User object still holds the previous tenant.
- Create a tenant with create_tenant and a role with create_role
- Add members with add_user_to_tenant and add_user_to_role
- Switch context with select_tenant, then reload the user
Use the HTTP API and turn access control on or off
Over HTTP you can register with POST /api/v1/auth/register and log in with POST /api/v1/auth/login, which takes form fields username and password and returns a bearer token. Send it as Authorization: Bearer. You can also create API keys at /api/v1/auth/api-keys and send them as X-Api-Key. The permissions routes live under /api/v1/permissions.
ENABLE_BACKEND_ACCESS_CONTROL is the master switch. It defaults to true, which is multi-tenant mode. Setting it to false gives single-user storage: every user reads and writes the same shared graph and vector databases, so use it only for a single-user deployment.
- Default user over HTTP has no password unless DEFAULT_USER_PASSWORD is set
- REQUIRE_AUTHENTICATION=true with access control off keeps logins but not isolation
- REQUIRE_AUTHENTICATION=false with access control on is ignored; auth is forced on with a warning
Debug PermissionDeniedError and missing datasets
Denied and empty are different results. Asking for a dataset id you cannot read raises PermissionDeniedError (HTTP 403). On recall or search, a dataset name that is not yours raises DatasetNotFoundError, even if it was shared with you. On writes such as remember, add or cognify, the same name silently creates a new dataset of your own.
Passing no datasets searches only what you can read, so a user with no grants gets an empty list. If a grant seems to work but the member cannot see the data, check that their active tenant matches the dataset's tenant.
- Use dataset ids, not names, when reading a dataset shared with you
- Confirm the granter holds share in their active tenant
- Reload the user after select_tenant
- Two users can each have a dataset called notes; the ids differ by owner and tenant
What people use it for
- Building a multi-user app where each user's notes go into their own dataset
- Setting up a tenant such as an organisation, with a Researcher role that reads a shared dataset
- Giving a colleague read-only access to a dataset without letting them delete it
- Working out why a recall call returns an empty list or raises PermissionDeniedError
Frequently asked questions
How do I install the cognee-permissions agent skill?
Download the ZIP from the skill's page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. In the Claude apps you can instead upload the ZIP under Settings, Capabilities, Skills.
Is the cognee-permissions skill free to use?
The skill is listed under the Apache-2.0 licence, which is stated on its page. Check the licence file in the cognee repository for the full terms before you use or redistribute it.
What do I need before using this skill?
You need the cognee Python SDK installed and access to a cognee server or SDK environment where you can create users and log in. The optional environment variables ENABLE_BACKEND_ACCESS_CONTROL, REQUIRE_AUTHENTICATION, DEFAULT_USER_EMAIL and DEFAULT_USER_PASSWORD control access behaviour.
Why does cognee raise PermissionDeniedError?
It is raised when you ask for a dataset id you cannot read, or when a grant is made by someone without share on that dataset in their active tenant. Check the dataset id, the granter's permissions and the active tenant. The skill walks through each case.
How do I share a cognee dataset with another user?
The granter must hold share on the dataset. Call authorized_give_permission_on_datasets with the recipient's id, the dataset's UUID, the permission (read, write, delete or share) and the granter's id. The recipient then uses dataset_ids with that UUID.
Should I turn off ENABLE_BACKEND_ACCESS_CONTROL?
Only for a single-user deployment. When it is false, all users read and write the same shared graph and vector databases, so other users' content is not filtered out. For multi-tenant use, keep it at its default of true.
How does this compare with other agent skills or access-control tools?
This skill covers only cognee's users, permissions and multi-tenancy model. It does not cover other tools. For production multi-tenant deployments with managed isolation, the skill directs you to contact social@cognee.ai.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you are building a multi-user or multi-tenant application on cognee, or you are debugging permission errors in one. Skip it for single-user local experiments, where the default setup already works. For production multi-tenant deployments that need managed isolation, contact cognee's team at social@cognee.ai rather than relying on this skill alone.
Download the skill