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

# orca keys

> List, issue, and revoke the tenant API keys that the CLI and SDKs authenticate with.

> **Last updated: 2026-09-06**

`orca keys` manages [tenant API keys](/concepts/api-keys): the `ao_` bearer keys that authenticate the CLI, the SDKs, and any direct caller of the `/api/*` control plane. A key inherits the role of whoever minted it. These are not the same as chat keys, which authenticate callers of a published agent through the gateway; those are managed with [`orca agents keys`](/cli/reference/agents#orca-agents-keys).

Every subcommand accepts the [global flags](/cli/reference/overview#global-flags). `orca keys create` prompts for a name when it is omitted in a terminal; in a pipe or script the name is required (exit code 2). Destructive subcommands prompt for confirmation in a terminal; in a script `--yes` is required or the command refuses (exit code 2).

## orca keys list

```bash theme={"dark"}
orca keys list
```

Lists every tenant API key with its id, name, role, creation time, last use, and state (`active`, `expires <time>`, or `revoked`). There are no page flags; the server returns the full set from `GET /api/api-keys`.

```bash theme={"dark"}
orca keys list --json | jq -r '.[] | select(.revokedAt == null) | .id'
```

Plain (piped) output is one tab-separated row per key: `id`, `name`, `role`, `createdAt`, `lastUsedAt` (or `-`), state. With `--json` the array of key metadata records is printed (no tokens; the server stores only a hash).

## orca keys create

```bash theme={"dark"}
orca keys create [name] [--expires <iso8601>]
```

Issues a new tenant API key. The plaintext token is shown exactly once and cannot be retrieved again. In a terminal it is revealed with a framed prompt; when stdout is a pipe, stdout carries only the token and the key's name and id go to stderr, so scripts can capture it directly; with `--json` the full issued-key record, including `token`, is printed.

| Flag                  | Type   | Default                    | Description                                         |
| --------------------- | ------ | -------------------------- | --------------------------------------------------- |
| `--expires <iso8601>` | string | server default (no expiry) | Expiry timestamp, sent to the server as `expiresAt` |

```bash theme={"dark"}
ORCA_API_KEY=$(orca keys create ci-deploy --expires 2027-01-01T00:00:00Z)
```

## orca keys revoke

```bash theme={"dark"}
orca keys revoke <id> [--yes]
```

Revokes a tenant API key by id. Anything authenticating with it stops working immediately.

| Flag    | Type    | Default | Description                  |
| ------- | ------- | ------- | ---------------------------- |
| `--yes` | boolean | `false` | Skip the confirmation prompt |

```bash theme={"dark"}
orca keys revoke key_abc123... --yes --json
```

```json theme={"dark"}
{ "id": "key_abc123...", "revoked": true }
```

<Note>
  Verified against orca-cli `cli-v0.5.0`.
</Note>