Skip to main content

​
Overview

API keys are durable, tenant-scoped credentials for programmatic access — the SDK, direct API calls, CI, and other automation. You present a key as a bearer token:
Orca tells API keys apart from interactive dashboard sessions (which authenticate with Clerk) by the ao_ prefix on the token. A value with that prefix is treated as a tenant API key; anything else in the Authorization slot is handled as a dashboard session.

​
Token format and environments

A token has the shape:
where <env> is a short environment identifier (for example live or test). Because the environment is baked into the token, each key is scoped to one environment — a test key and a live key are distinct credentials.
The plaintext token is shown exactly once, at creation. Copy it then and store it in a secret manager — Orca cannot show it again. If it is lost, revoke the key and issue a new one.

​
Roles: a key inherits its creator

An API key inherits the role of whoever created it — owner, admin, member, or viewer. A key issued by an admin can reach admin-only surfaces; a key issued by a member cannot. Scope keys deliberately by having them issued under an account with the right role. See Roles & Access.

​
Expiry and revocation

  • A key can be given an expiry; once past it, the key stops working.
  • A key can be revoked at any time, which immediately invalidates it.
Revoked or expired keys are rejected on every request.

​
Managing keys

Manage keys from the dashboard under Settings → API Keys, or through the API:

​
Using a key

Never send X-Tenant-ID — Orca strips it server-side. The tenant is always derived from the API key itself.

Manage API keys

Issue and revoke keys in the dashboard.

Roles & Access

How a key inherits its creator’s role.

SDK overview

Authenticate the SDK with an ao_ key.