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

# Authentication

> Key scope, administration, and rate limits

Send your API key on each brand request:

```http theme={null}
Authorization: Bearer amb_sk_<prefix>_<secret>
```

System administrators create keys in Amber's API key settings. That settings
page uses the existing API key feature flag. A brand-scoped key authorizes only
its brand slug; a global key can select a brand in the URL. Every request still
reads one brand's data.

Keys authorize the public read surface independently of the creating user's
roles. The creator is recorded for audit. A key does not impersonate that user
and cannot call the session-authenticated application API.

"Public" names the API-key integration surface, not anonymous public access or
a supplier portal. A key reads its authorized brand's full data, including
records the brand itself marked internal-only for suppliers (for example
`isInternal` media). Fields meant only for a supplier viewing a purchase order
or export are a separate, narrower concern from what the owning brand's own
key can read.

Use keys in server processes or secret stores. Do not embed them in browser
bundles or include them in URLs. Rotate keys through your administrator and
revoke keys that are no longer needed.

## Key management

Create your first key through **Amber settings**, using a system administrator
account. You do not need an existing API key. Copy the new key when it is shown;
you cannot retrieve its secret again from the key list.

Key creation, listing, rotation, and revocation use the separate admin API at
`/api/admin/api-keys`, authenticated by your Amber session. API keys cannot
administer keys. Rotation immediately revokes the old key.

Every operation in the public API reference is a read authenticated with an API
key. The reference does not include admin operations or session authentication.
The OpenAPI document itself is available without credentials.

## Access failures and limits

Missing, invalid, expired, revoked, and out-of-scope keys return `401`.
A valid key requesting an unavailable entity receives `404`.
Rate limiting is per key. A `429` response includes `Retry-After` in seconds.
See [Pagination and errors](/pagination) for a retrying client example.

Product expansion has an additional budget shared by the key across brands.
Each distinct `include` collection costs one credit; `include=all` costs 31.
The bucket holds 62 credits, allowing two full graphs immediately, and refills
at 1,000 credits per hour by default. The hourly refill follows the configured
public API request limit. A request still counts toward the usual request quota.

On `429`, wait for `Retry-After` before retrying. Request only the collections you
need to reduce credit use. Product reads without `include` and independent
collection pagination consume no expansion credits.