Permissions

Roles

Every person in your organization has one of three built-in roles: admin, collaborator or viewer. Every organization has the same three.

An admin chooses a person's role when they invite them, and can change it later on the User Management page in the Senso app or with senso users update.

Pass the role_id, not the role name. Each organization has its own IDs for the three roles. Look them up with senso roles list or:

curl "https://apiv2.senso.ai/api/v1/org/roles" \
  -H "X-API-Key: $SENSO_API_KEY"

What each role can do

Roles apply to people. An API key has no role, so it is never refused for one.

Permission keys

Each role is a set of permission keys, written action:resource. Admins hold every key below.

bypass:kb_acl is what gives admins and collaborators every file and folder in the knowledge base. kb:create_at_root lets them add files and folders at the top level.

senso permissions list and GET /org/permissions return the keys with a name and description for each.

Knowledge base access

Every file and folder in your knowledge base has its own access, separate from roles.

• Admins and collaborators reach every file and folder.
• Viewers reach only the files and folders shared with them, shared with a group they belong to, or made public.
• API keys reach every file and folder, unless you restrict the key. See API key access, below.

Without at least viewer access, a file or folder answers 404, exactly as if it did not exist. This applies to people and API keys, and to reads and changes alike, so Senso never reveals what you cannot see. A 403 means you can see the file or folder but your role on it does not allow the change.

Knowledge base roles

Each grant of access gives one of these roles on a file or folder:

Inheritance

Access flows down. Access to a folder covers everything inside it, however deep.

Root
├── Public Docs/          ← shared with Sam as "viewer"
│   ├── faq.pdf           ← "viewer"
│   └── Guides/           ← "viewer"
│       └── setup.md      ← "viewer"
├── Internal/             ← not shared with Sam, so no access
│   └── roadmap.docx      ← no access

Where two grants reach the same file, for example one shared with you and one shared with your group, the more permissive role wins.

Share a file or folder

To share, you need editor or owner on the file or folder. Admins and collaborators can share anything.

In the Senso app:

1. In the knowledge base, open the … menu on a file or folder and click Share.
2. Choose Group or User, then pick who to share with.
3. Choose Viewer or Editor.

With the CLI:

senso kb permissions list <id>
senso kb permissions add <id> --grantee-type user --grantee-id <userId> --role viewer
senso kb permissions update <id> <permissionId> --role editor
senso kb permissions remove <id> <permissionId>

The user_id is in the response when you invite someone, and senso users list shows each member's user_id and role. With the API, send the same fields to the file or folder:

curl -X POST "https://apiv2.senso.ai/api/v1/org/kb/nodes/{id}/permissions" \
  -H "X-API-Key: $SENSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"grantee_type": "user", "grantee_id": "<userId>", "role": "viewer"}'

A few rules apply wherever you share from:

• Only viewer and editor can be given. owner is only ever given automatically.
• A person or group has one grant per file or folder. Sharing again returns 409, so use update to change the role.
• A signed-in person cannot change or remove their own grant.

Groups

A group lets you share with several people at once. Admins create groups and add members in the Senso app, under Org Settings → Group Management. Deleting a group removes the access its members had through it.

Share with a group in the Senso app. An API key cannot see your groups, so the CLI and API keys can only share with people. For the same reason, senso kb permissions list shows only the grants to people.

Every organization also has a built-in Public group that everyone belongs to. Making a file or folder public gives that group viewer access.

API key access

A new key reaches your whole knowledge base, and can add and change anything in it. Restrict a key when an integration should only see part of it, for example "Public Docs" but not "Internal".

A restricted key:

• only reaches the files and folders you chose, and everything inside them
• only gets search results and folder listings from what it can reach
• needs editor on a folder to add or change anything in it

Any key can read a key's restrictions, including its own. Get the key's ID from senso api-keys list. An empty list means the key has full access:

curl "https://apiv2.senso.ai/api/v1/org/api-keys/{keyId}/kb-permissions" \
  -H "X-API-Key: $SENSO_API_KEY"

Or senso api-keys kb-permissions-get <keyId>.

One key per integration, restricted to what it needs. Then revoking one breaks nothing else.

Examples

When access is denied

Every error response has a message that says what went wrong.

Next steps

• API Keys — How keys work, and how to create, restrict and revoke one
• Errors — Every status the API returns
• Knowledge Base — Organize and manage your sources
• CLI Reference — Every senso users, roles and kb permissions command
• API Reference — Every endpoint, including roles, permissions and sharing