Authentication and scopes

Local operations require a signed-in desktop account and a separate bearer token with the required scopes. Account entitlements, token expiry and revocation are checked independently.

Desktop account requirement

Sign in or register in the desktop account window before accessing profiles, API, MCP or automation. A local API token cannot replace account sign-in. The server confirmation is valid locally for at most 15 seconds; expired confirmation or an unavailable account service blocks further protected operations. Stop and sign-out remain available.

GET /api/v1/account/status reports the confirmation state without exposing account credentials. Account binding and logout endpoints belong to the manager session and are not integration interfaces. The local profile store binds to the first confirmed account; another account cannot access that store.

403 code	Meaning
account.required / account.revoked / account.unavailable	Sign in again or restore the account connection.
account.owner_mismatch	Use the account bound to this local profile store.
account.feature_denied / account.limit_reached	The account plan does not allow the function or its configured limit is reached.

Bearer authentication

HTTP

Authorization: Bearer <LOCAL_API_TOKEN>
Content-Type: application/json

Send the header on authenticated requests. POST, PUT and PATCH require application/json, including operations with an empty JSON object. Token creation returns plaintext only once; token listings return metadata and a hint, not the original secret.

Select the minimum scopes

Scope	Purpose
profiles:read	Read profiles and profile metadata
profiles:write / profiles:delete	Create/update profiles / delete profiles
runtime:control	Start/stop profiles and operate browser pages
proxies:read / proxies:write	Read/manage proxies
cookies:read / cookies:write	Read/write cookies; values can grant access to accounts
secrets:read / secrets:totp	Read protected secrets / retrieve TOTP values
rpa:run / rpa:write	Run / configure RPA workflows
sync:control	Control live synchronization
extensions:write / kernels:manage	Manage extensions / browser kernels
trash:manage / settings:write / audit:read	Manage trash / write settings / read audit records
admin	Administrative operations including token management; satisfies other scope checks

Scope checks are only one layer: vault state, resource permissions, running state and writable storage can impose additional requirements. The OpenAPI field x-required-scopes lists the fixed route-level requirements; all listed scopes are required and admin satisfies those checks. Conditional checks based on request content or resources remain additional requirements. The table is a task guide, not a claim that every operation in a family has identical rights. Read auth.scope_missing details or inspect the installed MCP tools/list.

Token kinds and presets

Kinds are native, compat and mcp. The MCP preset omits admin, secrets:read and trash:manage, but still includes write operations and sensitive page/cookie access. The scripts preset omits admin, settings:write and secrets:read. Full includes all scopes. Choose “Eigene Rechte” in the desktop token dialog to select individual scopes for native API or MCP tokens. Explicit scopes replace the preset; they are not added to it. Tokens of kind mcp cannot be created with admin or secrets:read through the token API.

POST /api/v1/tokens

{
  "name": "Read-only integration",
  "kind": "native",
  "scopes": [
    "profiles:read"
  ],
  "expires_at": null
}

This administrative example has no expiry because expires_at is null. For a time-limited token, supply a Unix timestamp in milliseconds in the future. Do not grant admin to the integration just to let it create its own token; create it in the app with the needed rights.

Expiry, revocation and rotation

Missing or null expires_at means no automatic expiry. A token is rejected once expires_at is reached or after DELETE /api/v1/tokens/{id} revokes it. That DELETE revokes the credential, not the browser profiles. To rotate: create a replacement, update the client locally, verify a read-only call, then revoke the previous token. Never put a token in a URL, screenshot, repository or support log.