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

# Cherry Shot API: Authentication and API Key Management

> Generate Cherry Shot API keys, attach them to every request with a single header, manage agency keys, and handle auth and rate-limit errors.

Every request to the Cherry Shot API — except the public `/v1/health` endpoint — must include a valid API key. Keys authenticate your identity, authorize credit usage, and (for agency accounts) attribute activity to a specific client brand. There are no session tokens or OAuth flows; a single header is all you need.

## Get an API Key

Open the Cherry Shot dashboard, navigate to **Profile → API**, and click **Create key**. Give the key a descriptive name so you can identify it later, then click **Generate**.

The full key — the prefix `cs_` followed by 64 lowercase hexadecimal characters — is displayed **once, at creation**. Copy it immediately and store it in a secrets manager or environment variable. Cherry Shot stores only a one-way hash on its side, so the plaintext key cannot be retrieved or displayed again after you close the dialog.

<Warning>
  Treat your API key like a password. Anyone who holds it can spend your account's credits and access your generated assets. If a key is ever exposed — in a public repository, log file, or client-side bundle — revoke it from **Profile → API** immediately and generate a replacement.
</Warning>

## Send with Every Request

Include your key on every API call using one of the two supported headers. Both are equivalent; choose whichever fits your stack.

<CodeGroup>
  ```bash Authorization: Bearer theme={null}
  curl https://kyliwpyuseadbwawnsyd.supabase.co/functions/v1/api/v1/credits \
    -H "Authorization: Bearer cs_your_key_here"
  ```

  ```bash x-api-key theme={null}
  curl https://kyliwpyuseadbwawnsyd.supabase.co/functions/v1/api/v1/credits \
    -H "x-api-key: cs_your_key_here"
  ```
</CodeGroup>

## Agency Keys

If your account belongs to an agency workspace, every key you create is an **agency key** by default. Agency keys bill the agency's shared credit pool rather than an individual balance, which makes cost consolidation straightforward.

When you create an agency key, you can optionally pin it to a **client brand** (under **Profile → API → Client brand**). All requests made with that key are then attributed to the selected brand in your usage reports and dashboards. If the team member who created a key leaves the agency workspace, that key is automatically revoked.

## Limits

* **Rate limit:** Each key is limited to **60 requests per minute**. Exceeding this threshold returns a `429 rate_limited` response. Implement exponential back-off and retry logic in your integration to handle brief bursts gracefully.
* **Active keys per account:** You can hold up to **10 active keys** at one time. Revoke keys you no longer use to free up slots for new ones.

## Error Reference

The table below covers the two authentication-specific errors you are most likely to encounter.

| HTTP Status | `code`         | Meaning                                                             |
| ----------- | -------------- | ------------------------------------------------------------------- |
| `401`       | `unauthorized` | The key is missing, malformed, invalid, or has been revoked.        |
| `429`       | `rate_limited` | Your key has exceeded 60 requests per minute. Wait before retrying. |

For the complete error envelope format and a full list of error codes, see the [Errors guide](/guides/errors).