Authentication and permissions

Dockt authorizes every request from its authenticated principal, fixed or selected scope, and granted permissions.

Backend credentials

Both api_key and m2m credentials use bearer authentication for Dockt API requests. An API key is the bearer value. An M2M credential exchanges its client ID and one-time client secret at its returned token_url, then uses the short-lived access token as the bearer value.

Secret material is returned only when a credential is created. Later credential reads return metadata and a key hint, not the secret.

Credential scope

An API credential has exactly one scope_type:

• account: Manages the Account, its Workspaces, and account-scoped credentials.
• workspace: Operates within one Workspace for configuration and verification workflows.

The scope is fixed when the credential is created. The API doesn’t accept a request header or body field that changes it.

Browser sessions

Browser sessions can use POST /v1/auth/scope to select an available Account or Workspace. The active selection applies to later session requests. API credentials can’t call this operation to change their fixed scope.

Use GET /v1/auth/me to read the current authentication type, scope, permissions, available session scopes, and active scope.

Account permissions

Permission	Allows
account:read	Read the current Account.
account:write	Update Account metadata and manage account users where applicable.
workspaces:read	List and read Account Workspaces.
workspaces:write	Create and update Account Workspaces.
api-credentials:read	List credential metadata.
api-credentials:manage	Create, update, disable, and delete credentials.
social-compliance-packages:read	Read the social compliance package catalog.

Workspace permissions

Permission	Allows
workspace:read	Read the active Workspace.
workspace-configuration:read	Read Workspace Configuration, Assessment Policy, Monitoring Policy, and Job Profiles.
assessment-policy:write	Author and activate Assessment Policy revisions.
job-profiles:write	Author and activate Job Profile revisions.
monitoring-policy:write	Replace Monitoring Policy.
social-compliance-packages:read	Read the social compliance package catalog and policy data embedded in Assessment details.
notifications:manage	Manage Notification Destinations, event routes, secret rotation, and tests.
api-credentials:read	List Workspace credential metadata.
api-credentials:manage	Create, update, disable, and delete Workspace credentials.
assessments:read	List and read Assessments.
assessments:write	Create and update Assessments and manage linked Documents.
documents:read	List and read Documents, including summaries embedded in Assessment details.
documents:create	Upload Documents.
documents:delete	Withdraw standalone Documents.
decisions:read	Read Decisions and Outcomes, including Decisions embedded in Assessments.
decisions:outcome	Report a Decision Outcome.

The exact permission required by each operation appears in the API reference.

Assessment responses include data governed by other permissions:

Operation	Required permissions
List Assessments	assessments:read, decisions:read
Get an Assessment	assessments:read, decisions:read, documents:read, social-compliance-packages:read
Create or update an Assessment	assessments:write, decisions:read, documents:read, social-compliance-packages:read

These permissions apply even when the Assessment has no Documents or Decision. Create, update, and reuse_existing return the full detail representation; missing permissions return 403 before any changes. Idempotent retries recheck the caller’s current permissions before returning a saved response.

Authentication failures

A 401 Unauthorized response means the bearer value is missing, invalid, expired, or no longer enabled. The response includes WWW-Authenticate.

A 403 Forbidden response means authentication succeeded, but the credential scope or permission doesn’t allow the operation. Check GET /v1/auth/me before changing application logic or credentials.