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.

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.

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.

Authorization: Bearer

curl https://kyliwpyuseadbwawnsyd.supabase.co/functions/v1/api/v1/credits \
  -H "Authorization: Bearer cs_your_key_here"

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.