API keys & tokens

Workspace API keys for applications and personal access tokens for automation: scopes, environments, rotation and limits.

On this page

Worksi uses two kinds of credentials. Both are shown once when you create them and are stored only as SHA-256 hashes.

Table: Credential, Format, Belongs to, Use it for
Credential	Format	Belongs to	Use it for
API key	`aiw_sk_live_…`	A workspace and environment	Applications: gateway calls, SDK telemetry, OpenTelemetry, MCP agent tools and the MCP gateway
Personal access token	`aiw_pat_…`	A user in one organization	Scripts and automation against the REST API, and MCP operator tools

API keys#

Create keys in Governance → API keys, or with POST /api/v1/api-keys. A key is bound to one workspace and one environment. That environment decides the tenant, the capture mode and the policies of every request made with the key, and clients cannot override them: a key can only write into its own environment.

Send the key as a bearer token. The Anthropic SDKs send it as x-api-key, and Azure-style clients can use the api-key header; the gateway accepts all three. The MCP endpoints read the bearer token only.

HTTP

Authorization: Bearer aiw_sk_live_…x-api-key: aiw_sk_live_…api-key: aiw_sk_live_…

Scopes#

New keys get all three scopes. Remove the ones a service does not need.

Scopes
Scope	Allows
`gateway:invoke`	Inference (`/v1/chat/completions`, `/v1/responses`, `/v1/embeddings`), `/v1/models`, control status and approval requests
`traces:write`	`/v1/traces`, `/v1/otlp/v1/traces`, `/v1/outcomes` and approval requests
`control:read`	Control status and approval polling only

A revoked, expired or unknown key gets 401 invalid_api_key. A missing scope gets 403 insufficient_scope.

Rate limits, expiry and rotation#

Rate limit: an optional per-key limit in requests per minute. Above it the gateway answers 429 rate_limited with Retry-After.
Expiry: an optional date after which the key stops working.
Rotate issues a new secret and revokes the old one. Revoke stops a key at once; the gateway drops its cached copy within seconds.
Creating, rotating and revoking keys is recorded in the audit log.

Good practice#

Use one key per service and per environment, so you can revoke one without touching the others.
Keep keys in a secret manager. Never put them in source control or in code that runs on your users’ devices (browsers, mobile apps): call the gateway from your backend.
Rotate keys when people leave the team.

How many keys#

How many keys
Plan	API keys
Starter	5
Pro and the trial	25
Business	200
Enterprise	Custom

Personal access tokens#

A personal access token (PAT) acts as you. Its permissions are your current role in the organization, checked every time the token is used: if your role changes or you leave the organization, the token follows. Create tokens in Settings → Personal access tokens, optionally with an expiry, and revoke them there at any time.

Use a PAT with the REST API (the same API the console uses) at https://worksi.ai/api/v1:

Terminal

curl -s "https://worksi.ai/api/v1/incidents?status=open" \  -H "Authorization: Bearer aiw_pat_…"

A token belongs to one organization, so no organization header is needed. For the MCP operator tools (list and acknowledge incidents, pause agents, decide approvals), see MCP.

Questions? Email info@xeoo.io.