Availability

Scale and Enterprise only. Your account must be enrolled in the invite-only beta, your chosen surface must be enabled, and write scopes must be approved for your cohort. Free, Trial, Starter and Growth accounts cannot create or use keys. Quota overrides cannot grant plan access.

Requests also require an active, unexpired key, all required scopes, an owned brand bound to the key, and an eligible account and brand. Feature availability and entitlement are checked again for operations. Recovery actions have specific exceptions documented in their reference pages.

API keys

Create keys in the app (Settings → API keys) or via POST /v1/api-keys.

curl -s "${CITERA_API_BASE_URL%/}/v1/brands" \
  -H "Authorization: Bearer $CITERA_API_KEY" \
  -H "Accept: application/json"

curl -s "${CITERA_API_BASE_URL%/}/v1/brands" \
  -H "Authorization: Bearer $CITERA_API_KEY" \
  -H "Accept: application/json"

curl -s "${CITERA_API_BASE_URL%/}/v1/brands" \
  -H "Authorization: Bearer $CITERA_API_KEY" \
  -H "Accept: application/json"

curl -s "${CITERA_API_BASE_URL%/}/v1/brands" \
  -H "Authorization: Bearer $CITERA_API_KEY" \
  -H "Accept: application/json"

A 401 response includes WWW-Authenticate: Bearer realm="rankad", error="invalid_token".

Session tokens (key management and usage only)

The routes /v1/api-keys* and /v1/usage also accept a Citera (Supabase) session JWT. This is how the Settings page works. A session principal:

• is verified by the service;

• receives only the keys:manage scope and no brands;

• is accepted on the API surface only (never on MCP);

• must still satisfy api.enabled and the Scale/Enterprise plan check.

Browser key-management calls are restricted to approved application origins.

Optional client headers