Authorization

​

Roles

Every user in a tenant has one of three roles: Owners and Admins have unrestricted access to all content — no path permission checks apply. The User role is where path permissions come into play.

​

Path permissions

Path permissions control which parts of the knowledge base a User can access. Permissions are granted on specific paths and automatically apply to everything underneath.

​

How it works

When you grant a User read access to /shared/engineering, they can read:

• /shared/engineering
• /shared/engineering/design-doc
• /shared/engineering/design-doc/v1/introduction
• Everything else under /shared/engineering

​

Capabilities

​

Personal workspace

Every user automatically has read-write access to their own workspace at /users/{user_id}. This is where their threads, personal documents, and other user-specific content lives.

​

Permission examples

Given these permissions for a user:

• Read-only on /shared
• Read-write on /shared/output
• Read-write on /users/abc

Here’s what they can do:

​

How authorization works for different operations

​

Managing permissions

Admins and Owners can manage User permissions through the permissions API.

​

Limits and validation

• Each user can have a maximum of 50 path permissions.
• Redundant permissions are rejected. For example, if a user already has read-write on /a, granting read-only on /a/b is unnecessary (the broader permission already covers it).
• Permissions can be escalated. For example, if a user has read-only on /a, you can grant read-write on /a/b to give them write access to a specific subtree.