Authenticate your backend

Dockt supports API keys and machine-to-machine (M2M) credentials for backend integrations. Create a workspace-scoped credential in the Dockt control plane, then store the returned secret immediately. Secret material is returned only when the credential is created.

Choose a credential type

Use an api_key when you want a long-lived opaque bearer credential with the least setup. You can set an expiration when you create it.

Use an m2m credential when your service can exchange a client ID and client secret for short-lived access tokens. Refresh the token before its expires_in period ends.

Both credential types have a fixed account or workspace scope and an explicit allowed_scopes permission list.

Use an API key

Store the one-time api_key value as a secret and export it for the examples:

export DOCKT_API_BASE_URL='https://api.dockt.com'
export DOCKT_API_TOKEN='REPLACE_WITH_API_KEY'

Send the key as a bearer token:

curl --fail-with-body \
  -H "Authorization: Bearer $DOCKT_API_TOKEN" \
  "$DOCKT_API_BASE_URL/v1/auth/me"

Use an M2M access token

Store the one-time client_secret together with the returned client_id and token_url:

export DOCKT_CLIENT_ID='REPLACE_WITH_CLIENT_ID'
export DOCKT_CLIENT_SECRET='REPLACE_WITH_CLIENT_SECRET'
export DOCKT_TOKEN_URL='REPLACE_WITH_TOKEN_URL'

Exchange the client credentials for an access token:

token_response="$(
  curl --fail-with-body --silent --show-error \
    -X POST "$DOCKT_TOKEN_URL" \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode "client_id=$DOCKT_CLIENT_ID" \
    --data-urlencode "client_secret=$DOCKT_CLIENT_SECRET" \
    --data-urlencode 'grant_type=client_credentials'
)"

export DOCKT_API_TOKEN="$(printf '%s' "$token_response" | jq -r '.access_token')"

The token response includes access_token, token_type, and expires_in. Cache the token on your server and repeat the exchange before it expires.

Grant only required permissions

For a complete assessment workflow, a workspace credential typically needs:

• assessments:read
• assessments:write
• documents:read
• documents:create
• decisions:read

Add webhooks:manage if the same service configures webhook endpoints. Add decisions:outcome only if it reports what happened after a Decision.

For a standalone document workflow, use documents:create and documents:read. Add documents:delete if your integration withdraws documents.

The authentication and permissions reference lists every public permission.

Verify the credential

Call GET /v1/auth/me after loading your bearer token:

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $DOCKT_API_TOKEN" \
  "$DOCKT_API_BASE_URL/v1/auth/me" | jq '.data | {
    auth_type,
    api_credential_type,
    principal_scope_type,
    permissions,
    active_scope
  }'

Confirm that principal_scope_type is workspace before calling workspace routes. Confirm that permissions includes every operation your integration will use.

Protect and rotate credentials

• Keep credentials in a server-side secret manager.
• Use separate credentials for separate applications and environments.
• Disable or delete a credential before replacing it.
• Never log bearer tokens, API keys, client secrets, or document bytes.
• Treat a 401 response as an authentication failure and a 403 response as a scope or permission failure.