import { Code } from '@astrojs/starlight/components';
import { apiOrigin } from '../../../lib/docs-env';
import ScopeTable from '../../../components/ScopeTable.astro';

API keys authenticate requests to the public API. Each key is bound to one region and one mode — see [Modes and regions](/developers/modes-and-regions).

## Before you start

You need an organization membership and an active mode (`test` or `live`) selected in the sidebar. Keys you create reflect the active mode.

## Create a key

Open **Developers → API keys** and click **New API key**. Pick a key type:

- **Secret key** (`ah_sk_…`) — server-to-server. Carries scopes. Keep private.
- **Publishable key** (`ah_pk_…`) — browser-side SDK. Bound to one or more origins; does not carry scopes.

Give the key a label that identifies where it runs (for example `production-api`). Pick an expiration if you want the key to auto-revoke. For publishable keys, list every allowed origin (one per line); bare `*` is rejected.

The key is shown once and is then unrecoverable. Copy it into a secrets manager before closing the dialog.

## Scopes

Secret keys carry a list of scopes, grouped below by what they control. Grant the minimum your integration needs. For common integration patterns, see [Choosing scopes for your key](/developers/choosing-scopes).

<ScopeTable />

A call without the required scope returns `insufficient_scope` (HTTP 403) and names the missing scope in the response. See the [API error codes](/api/errors).

## Store the key

Treat the key like a password. Store it in a secrets manager (for example, 1Password) and never commit it. We can only display the key once at creation. If you lose it, rotate it.

## Use the key in a request

Send the key in the `Authorization` header against the endpoint that matches the region:

<Code
  code={`curl -i ${apiOrigin('us')}/v1/me \\\n  -H "Authorization: Bearer ah_sk_us_test_<your-key>"`}
  lang="bash"
/>

Every response includes an `X-Request-Id` header. Capture it in your logs — support tickets that include the request ID get triaged faster.

## Troubleshooting

See [Why was my API key rejected?](/developers/faq/api-key-rejected). Common causes: region mismatch, missing scope, or the key has been revoked. To cycle a key out, see [Rotate or revoke an API key](/developers/api-keys-rotate).