Permissions and Organization Access

Every request passes three gates:

1. Token scope.

2. Tenant boundary: Personal, Org, and optionally workspace context.

3. Object permission: resource role, workspace role, Org role, or public access.

The most permissive applicable role wins, except an explicit resource role caps the document tier. Private resources suppress ordinary workspace viewer/editor access; the creator, workspace admin, or explicit share can still access them.

Practical rules

• An Org key cannot access a different Org.

• A Personal key cannot access Org workspaces.

• A valid key does not bypass document permissions.

• A 404 may be returned when revealing resource existence would leak information.

• Use GET /api/v1/resources/{resource_id}/permissions to inspect explicit resource roles.

Org roles

Org owners and admins can manage Org-level settings and memberships, subject to the endpoint scope. Workspace roles still matter for workspace-local operations.

For AI agents, expose the smallest tenant and scope set that completes the task. Do not use an Org-wide write key for a read-only indexing worker.