API keys
Organization-owned keys with project scopes, one-time secrets and overlapping rotation.
Business API keys belong to the organization and are bound to one project. They continue working when their creator is demoted or removed. Owners and admins create and revoke keys in the console. Direct keys stay bound to the user's own active identity and membership.
Create a key
Open API keys, enter a name and choose a preset or Custom scopes. An optional
expiry is expressed in seconds (at least 60). The secret is shown once. Store it on your
backend as ARC0_API_KEY; keep it out of browser code, logs and source control.
| Preset | Scopes |
|---|---|
| Runtime | execute, connect:create |
| Integration | Runtime plus users:manage, connections:manage, embedded:manage, mcp:keys, apps:read |
| Read only | Every :read scope |
| Full access | Every scope below except funded_access:manage, which must be selected explicitly |
Direct organizations offer their self-bound runtime and custom scopes only.
Scope catalog
| Scope | Access |
|---|---|
execute | Search, execute, proxy and execution results |
connect:create, connect:group | Create Connect links; group connections also require connect:group |
users:read, users:manage | End users, groups and memberships |
connections:read, connections:manage | Connection reads and management |
apps:read, apps:manage | Project apps, tools and version pins |
auth_configs:read, auth_configs:manage | OAuth configurations; secrets remain write-only |
connect_settings:read, connect_settings:manage | Connect branding, domains and return origins |
embedded:manage | Embedded origins, tickets and revocation |
policies:read, policies:manage | Policies |
approvals:read, approvals:decide | Approval reads and decisions |
audit:read, usage:read | Audit and usage reads |
funded_access:read, funded_access:manage | Organization funded-access setting; writes require current owner/admin authority |
events:manage, sources:manage | Events/webhooks and custom app sources |
keys:manage | Create, rotate and revoke project keys with no broader scopes |
mcp:link, mcp:keys | Identity link tickets and short-lived user-bound runtime keys |
This catalog defines permissions for management operations as they become available;
a scope alone does not make a new endpoint available. manage includes the same resource's
read; approvals:decide includes approvals:read. The legacy connect spelling remains
an alias of connect:create. Scopes do not grant credential export.
Environments
arc0_sk_live_— Production projectarc0_sk_test_— Development projectarc0_rk_— User-bound runtime child (at most 24 hours)
Keys work only in their bound project. A configuration that disagrees with the project
returns 403 environment_mismatch. Existing keys retain their original secrets and prefixes
when ownership migrates; their permissions and expiry stay the same. Business keys whose
creators had already lost owner/admin membership before migration remain disabled.
Backend key management
Send Authorization: Bearer $ARC0_API_KEY from your backend:
GET /v1/keysto list business keys no broader than the caller.POST /v1/keyswith{name, permissions}or{name, preset}and optionalexpiresIn.POST /v1/keys/:id/rotatewith{overlapHours}(default 24, range 0–168).DELETE /v1/keys/:idto revoke.
These routes require an unbound business key with keys:manage. If the calling key expires,
created keys inherit that expiry as a ceiling, including when expiresIn is omitted.
A replacement created through rotation also cannot outlive the calling key. A caller cannot create,
rotate or revoke a key with broader scopes, or manage keys in another project. Subject-bound
runtime keys cannot manage business keys. Responses from creation and rotation contain
{data: {id, key, configId}}; copy the secret from data.key.
Send Idempotency-Key on creation and rotation to retry the same request safely. A retry
returns the first result for up to 24 hours, including the original generated secret.
Expired retained records return 410 idempotency_expired; reconcile the original key before
issuing a new request. Reusing that header with
different input returns 409 idempotency_conflict. The caller must still be active and hold
the target scopes when replaying a response. Keep retry headers and responses in your backend.
Rotate and revoke
Rotate (24h overlap) in the console creates a replacement with the same scopes, project and expiry. The old key works until its existing expiry or the end of the overlap, whichever comes first. Update callers during that window. Backend rotation permits zero hours for immediate expiry. Runtime children depend on their original parent's validity, so replace those children before their parent expires.
Revocation stops the selected key immediately. Independent business keys it created, including
rotated replacements, remain valid until their own expiry or revocation; revoke those individually.
Runtime children still require an active parent. Expired and revoked key identities remain stored for
audit and parent references. Better Auth stores a hash of the secret. When a management
POST uses Idempotency-Key, Arc0 also retains the first response encrypted so a retry can
return the same secret; it does not retain a plaintext copy. Expired retry records are removed through migrator maintenance. Account
compromise recovery explicitly revokes keys created by the affected account and their delegated descendants.
Offboard an issuer
In API keys → Offboard a key issuer, choose Revoke issued keys for a member, or enter a former member's user ID. Confirm Revoke all issued keys to stop every key they issued across this organization, including delegated keys and rotated replacements. Each revocation is audited. Keys in other organizations are unaffected.
Rotation counts as issuance: offboarding an admin also revokes replacements they rotated for other issuers, and those replacements' descendants. This deliberately fails safe when an issuer is removed or compromised.
This action works in both Embedded and Direct organizations. In Direct mode, removing a member
already disables that member's subject and keys; explicit offboarding additionally revokes
keys and replacements attributed to them. Owners and admins can also invoke it before removal.
Use an actual member user ID or a known former human issuer's ID. Organization IDs, API key IDs,
unknown IDs and unrelated users are rejected with 400 invalid_issuer_user. Retained issuer
attribution allows offboarding after a former member's account was deleted.
Removing a member offers this action automatically. In Embedded organizations, choose
Keep keys when production keys should continue working. In Direct mode, this skips the
additional issuer cascade; it never reactivates keys already disabled by member removal. Owners and admins can also call
POST /v1/orgs/:orgId/keys/revoke-issued with {userId} using their console session and
trusted origin; API keys cannot invoke this staff action. Rotation retains the issuer chain
so subsequent offboarding and account compromise recovery still reach replacements.
Connect sessions and return origins
connect:create creates hosted Connect sessions; the stored legacy connect name also works.
Both spellings remain valid when the hosted session reads its catalog or selects an app.
Creator demotion/removal does not revoke that organization-owned issuer; explicit key revocation,
expiry, scope loss and project/subject restrictions still stop the hosted session.
GET /v1/connect-sessions/return-origins requires connect_settings:read.
PUT /v1/connect-sessions/return-origins requires connect_settings:manage, which also permits reads.
For compatibility, both endpoints continue accepting embedded:manage. This compatibility applies
only to return origins: it does not grant other Connect settings permissions. Settings scopes do
not grant embedded-session management. Custom keys should request the canonical settings scopes;
the Integration preset retains its embedded-management grant and uses this compatibility path.