Authentication

Authenticate the client

An API client is the software identity authenticated by a Bearer credential. Send Authorization: Bearer <credential> on every protected API operation. Use HTTPS outside Development. Browser cookies do not replace the API’s Bearer authentication.

Authorization: Bearer EXAMPLE_TOKEN_NOT_VALID

Identity and worker mapping

A client belongs to one organisation and has client-level scopes shared by its credentials. A client may map to an active worker resource. That resource must be assigned to a task for task ownership; a scope alone never grants ownership. GET /api/v1/identity reports the client, organisation, nullable resource and scopes.

An unmapped client returns resource: null. It can inspect identity and receives empty owned-work lists, but cannot operate on a task. Removing/changing a mapping changes current access immediately. Resource identity and human login identity are separate concepts.

Credential lifecycle

1. An administrator configures a client and grants only needed scopes.
2. The administrator issues a credential; its secret is displayed once.
3. For rotation, issue a replacement while the old credential remains usable. Move the worker to the replacement and verify it.
4. Explicitly revoke the old credential. Revoking a client invalidates its credentials together.

Credentials currently have no automatic expiry. Administrator-managed rotation and explicit revocation are the lifecycle policy. A credential also depends on an active organisation, active sponsoring user and active non-viewer sponsoring membership. A mapped resource must remain an active agent. A viewer sponsor, deactivated sponsor/user/organisation/resource or revoked client/credential causes authentication failure.

Handle credentials as secrets

• Use server-side/agent secret storage and restrict access to the worker process.
• Never commit credentials, embed them in browser bundles or put them in URLs.
• Redact Authorization headers in application, proxy and diagnostic logs.
• Rotate and revoke if exposure is suspected.
• Do not assume a new credential gives its client a fresh independent rate quota.

When access fails

A 401 authentication_failed requires fixing the credential or its current lifecycle state. A 403 normally means a valid client lacks a scope or current task assignment. Do not retry a permission denial as a transient outage. Read error recovery and write preconditions.