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.

PresetScopes
Runtimeexecute, connect:create
IntegrationRuntime plus users:manage, connections:manage, embedded:manage, mcp:keys, apps:read
Read onlyEvery :read scope
Full accessEvery scope below except funded_access:manage, which must be selected explicitly

Direct organizations offer their self-bound runtime and custom scopes only.

Scope catalog

ScopeAccess
executeSearch, execute, proxy and execution results
connect:create, connect:groupCreate Connect links; group connections also require connect:group
users:read, users:manageEnd users, groups and memberships
connections:read, connections:manageConnection reads and management
apps:read, apps:manageProject apps, tools and version pins
auth_configs:read, auth_configs:manageOAuth configurations; secrets remain write-only
connect_settings:read, connect_settings:manageConnect branding, domains and return origins
embedded:manageEmbedded origins, tickets and revocation
policies:read, policies:managePolicies
approvals:read, approvals:decideApproval reads and decisions
audit:read, usage:readAudit and usage reads
funded_access:read, funded_access:manageOrganization funded-access setting; writes require current owner/admin authority
events:manage, sources:manageEvents/webhooks and custom app sources
keys:manageCreate, rotate and revoke project keys with no broader scopes
mcp:link, mcp:keysIdentity 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 project
  • arc0_sk_test_ — Development project
  • arc0_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/keys to list business keys no broader than the caller.
  • POST /v1/keys with {name, permissions} or {name, preset} and optional expiresIn.
  • POST /v1/keys/:id/rotate with {overlapHours} (default 24, range 0–168).
  • DELETE /v1/keys/:id to 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.

On this page