Keys and accounts

# Authentication and keys

Every metered request carries a key. A key is a bearer credential: whoever holds it can spend its balance.

**On this page**

- [Sending a key](https://inference.dagon.so/docs/authentication#sending-a-key)
- [Kinds of credential](https://inference.dagon.so/docs/authentication#kinds-of-credential)
- [Create a key](https://inference.dagon.so/docs/authentication#create-a-key)
- [Read and delete a key](https://inference.dagon.so/docs/authentication#read-and-delete-a-key)
- [Why a key stops working](https://inference.dagon.so/docs/authentication#why-a-key-stops-working)
- [Keeping keys safe](https://inference.dagon.so/docs/authentication#keeping-keys-safe)

## Sending a key

Send `Authorization: Bearer <key>`, or `x-api-key: <key>` (what Anthropic SDKs send). A metered request with neither, and no x402 payment, is answered `402 payment_required` with x402 requirements; other routes answer `401 missing_api_key`.

curl

```curl
curl https://inference.dagon.so/v1/key -H "Authorization: Bearer $DAGON_KEY"
```

## Kinds of credential

| Prefix | What it is | How you get it |
| --- | --- | --- |
| `gk_` | Prepaid key with its own balance. A root key (no parent) can mint child keys. | `POST /v1/keys`, the console, a [keyless x402 payment](https://inference.dagon.so/docs/x402) (`x-dagon-key`), or a root minting a [child key](https://inference.dagon.so/docs/child-keys) |
| `ses_` | Console session for a passkey account. Manages the account; cannot spend. | [Passkey login](https://inference.dagon.so/docs/passkeys) |

## Create a key

POST `/v1/keys`

No credentials. Body `{"name"?}` (at most 80 characters). Returns `201 {key, data}`; `key` is shown once. Key creation is rate limited per client address (`429 rate_limited` with `Retry-After`), and is `403 signup_disabled` when self-service signup is off. `GET /v1/payment-methods` reports whether signup is enabled.

## Read and delete a key

GET `/v1/key`

Returns `data` with the key's `id`, `kind`, `name`, `parent_id`, `created_at`, `expires_at`, `last_used_at`, `disabled`, `suspended`, balances (`funded_micros`, `spent_micros`, `reserved_micros`, `available_micros`) and `children_count`.

DELETE `/v1/key`

Revokes the key. A child key deleting itself hands its available balance back to its root. A console session cannot delete its own account (`403 forbidden`).

## Why a key stops working

| Answer | Meaning |
| --- | --- |
| `401 invalid_api_key` | Unknown or revoked key. |
| `401 key_expired` | The key had an `expires_at` that has passed. |
| `401 key_disabled` | The key or its root account was deleted or disabled (by the operator or a sanctions hit). |
| `403 key_suspended` | An automatic safety suspension. The message gives the appeal address. See [Safety](https://inference.dagon.so/docs/safety). |
| `401 session_not_allowed` | A `ses_` token was sent to a metered route. Use a key you minted. |

## Keeping keys safe

- Store keys in a secret manager or password manager, never in client-side code.
- Give each app, agent or teammate its own [child key](https://inference.dagon.so/docs/child-keys) with only the balance it needs, so a leak costs at most that.
- When you report a problem, quote only the key id or the `gk_` prefix, never the full key.

Lost keys

We cannot show a key again, verify who owns one, or recover, transfer or refund a lost key.

Last updated 2026-11-07

[Previous **Models and pricing**](https://inference.dagon.so/docs/models) [Next **Child keys**](https://inference.dagon.so/docs/child-keys)