> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orcapods.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Keys

> Durable ao_ tenant keys for authenticating SDK, API, and automation calls — scoped to an environment and inheriting their creator's role.

## 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:

```
Authorization: Bearer ao_...
```

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:

```
ao_<env>_<random>
```

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.

<Info>
  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.
</Info>

## 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](/concepts/access-control)**.

## 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:

| Action       | Endpoint                    |
| ------------ | --------------------------- |
| List keys    | `GET /api/api-keys`         |
| Issue a key  | `POST /api/api-keys`        |
| Revoke a key | `DELETE /api/api-keys/{id}` |

## Using a key

```bash theme={null}
curl https://api.orcapods.ai/api/profiles \
  -H "Authorization: Bearer ao_live_XXXXXXXXXXXXXXXXXXXXXX"
```

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

## Related

<CardGroup cols={3}>
  <Card title="Manage API keys" icon="key" href="/dashboard/api-keys">
    Issue and revoke keys in the dashboard.
  </Card>

  <Card title="Roles & Access" icon="lock" href="/concepts/access-control">
    How a key inherits its creator's role.
  </Card>

  <Card title="SDK overview" icon="code" href="/sdk/overview">
    Authenticate the SDK with an ao\_ key.
  </Card>
</CardGroup>