Roles and permissions

A component permission determines which operation you may attempt. Department, ownership, sharing and other record rules determine where that operation is allowed.

Component levels#

An endpoint may require additional authority or a record-specific check. A role name alone does not describe all access.

Read your permissions#

After signing in, call GET /api/users/me/permissions.

const response = await fetch("/api/users/me/permissions", {
  credentials: "same-origin",
});
if (!response.ok) throw new Error(`Permissions: ${response.status}`);
const { permissions } = await response.json();
const mayAttemptDocumentEdit =
  ["write", "admin"].includes(permissions["docs.documents"]);

The response includes a permissions map and management context such as headedDepartmentIds and hasManagedUsers. Use these to guide the interface; the server still checks each request.

Common keys#

This is a selection, not an exhaustive catalog.

Record access example#

Deleting a document passes a docs.documents: write route check and then a document-level administrative-access check. Component write access alone does not allow deleting an arbitrary document.

A shared document can also be readable without being editable. See the Documents API.

Investigate a 403#

1. Confirm the account with GET /api/auth/me.
2. Check the endpoint's required component and level.
3. Check the record's department, ownership and sharing.
4. Read the response body. Component refusals may identify component and required; record-level refusals can have a different shape.
5. Ask an authorized administrator to review the specific missing access.

Do not repeatedly retry an unchanged request. Hiding an unavailable action improves the interface but does not enforce authorization. Read Workspace access for the product model.