Authentication¶

Status: Current | Last reviewed: 2026-10-12

External callers authenticate against TrueServe's HTTP APIs with bearer tokens. All authenticated users can mint Personal Access Tokens from Profile → Settings. The server derives a personal token's access from the user's current tenant permissions, so removing Authentik access removes token access too. Tenant administrators with AIManager:ManageConfiguration can create and permanently delete tenant tokens under Configuration → API Tokens.

Interactive management clients such as Claude Code and Codex should use the Agent Studio OAuth flow instead of copying a long-lived API token into tool configuration. OAuth delegates login to the existing SSO session and binds the grant to one tenant, one resource, and explicit management scopes.

/login?local=1 explicitly selects the existing local username/password form instead of automatically redirecting to SSO. /login continues to use the deployment's SSO settings. The query parameter changes only the client login flow; it does not issue a session or change authorization.

The form calls the existing POST /api/auth/login endpoint, which verifies the local password, resolves active tenant membership, expands role permissions and sets the session cookie. SSO-only records do not acquire a local password through this option. For local development, e2e/fixtures/e2e-user.ts provisions ordinary password accounts with a local-database guard; its default tenant is trueserve. Use a non-admin Viewer membership when testing read-only UI.

e2e/local-login.spec.ts verifies rejection of invalid credentials, successful Viewer login, permission preservation and the unchanged default SSO redirect.

Management OAuth¶

The management MCP advertises protected-resource metadata at /.well-known/oauth-protected-resource/api/mcp/authoring; authorization-server metadata is at /.well-known/oauth-authorization-server. The flow supports dynamic public-client registration, authorization code with mandatory S256 PKCE, refresh-token rotation, and revocation.

OAuth access tokens use the tsfo_ prefix and last one hour. Refresh tokens use tsfr_, rotate on use, and belong to a 30-day revocable family. The database stores hashes, not plaintext. Every authenticated request re-checks the user's current tenant membership and intersects the original grant with current permissions.

Management scope	Permits
`agents:read`	Inspect agents of every type, including workflow drafts
`agents:write`	Create, validate and save agent/workflow drafts
`agents:publish`	Publish any agent type
`agents:debug`	Read conversation and workflow-run diagnostics
`studio-ai:run`	Use AI authoring with the required write/read grants

Viewer can obtain read/debug grants. Builder and Admin can also obtain write/publish/AI-authoring grants. Old workflow scope names normalize to the corresponding agent scopes; there is no separate workflow authorization gate.

Token format¶

tsf_<40 hex chars>

Segment	Values	Purpose
`tsf_`	constant	Identifies the credential as a TrueServe token
`<40 hex chars>`	random	The actual secret, shown once at creation time

The platform stores only a SHA-256 hash. There is no recovery — if the secret is lost, mint a new one and revoke the old.

Token internals live in the repo at apps/ai-manager/lib/api-token-auth.ts, apps/ai-manager/lib/db-api-tokens.ts, and the api_tokens table.

Sending the token¶

Send the token as a bearer credential:

POST /api/v1/events HTTP/1.1
Host: events.vanguard.dev.trueserve.deloitte.com
Authorization: Bearer tsf_0123456789abcdef0123456789abcdef01234567
Content-Type: application/json

The token also accepts the X-API-Key header for callers (Salesforce Apex, some legacy on-prem systems) that cannot send Authorization. Prefer Authorization.

Scopes¶

Personal tokens do not accept editable scopes. They receive the canonical scopes that correspond to the user's current effective tenant permissions. Tenant tokens may store scopes explicitly, but new integrations should use the same canonical scope names.

Scope	Permits
`agents:read`	List published agents and read sanitized integration metadata
`agents:run`	Browse and execute saved agents of every type, including workflows
`agents:manage`	Create, edit, publish, delete, import/export and run agents of every type
`emulator:run`	Mint short-lived phone-emulator sessions for published agents
`tools:manage`	Manage tools, catalogs, surfaces and multimodal configuration
`configuration:manage`	Administer tenant configuration and tokens

Legacy pipeline/call read and run scopes map to agents:run. Pipeline writes, event writes and the old workflow management scope map to agents:manage. Tool/catalog scopes map to tools:manage; settings/integration management scopes map to configuration:manage.

agents:manage implies agents:run, agents:read and emulator:run. agents:run implies the two narrow read/emulator integration scopes. A Viewer personal token therefore executes existing agents without authoring access.

Skipped paths¶

A small set of paths are exempt from authentication so health checks and OpenAPI introspection work:

/health, /healthz, /openapi.json
/docs, /redoc (Swagger UI for human inspection in dev)
/api/v1/webhooks/<provider> paths whose security comes from the provider's own signing scheme (Salesforce signed JWT, Webex HMAC, etc.)

Rotating tokens¶

Best-practice rotation:

1. Mint a new token with the same scopes and a sensible expiry.
2. Switch consuming systems to the new token.
3. Verify health.
4. Revoke the old personal token, or delete the old tenant token.

Both tokens are valid simultaneously between steps 1 and 4 — that's intentional; it's how you avoid downtime.

The master encryption key that wraps integration credentials is rotated separately — see rotate master encryption key.

Rate limits¶

Per-token rate limits default to 100 req/s with a 30-second burst. Tenants on a paid plan can raise this. Exceeding the limit returns 429 Too Many Requests with a Retry-After header — back off, don't hammer.