Skip to main content
Every request to the OpenQuota public API requires a scoped API key in an Authorization: Bearer <key> header. Keys are org-scoped — the key implicitly identifies which org the request belongs to.

​
Obtaining a key

Keys are generated in the OpenQuota admin UI (Settings → API Keys). Only admins can create or revoke keys. On creation you pick:
  • Name — a human-readable label for this key’s purpose.
  • Scopes — the minimum set of scopes this key needs. See below.
  • Rate limit — requests per minute. Defaults to 1000.
The raw key is returned once from the create call. It starts with oqp_ followed by 64 hex characters of entropy. The server stores only a SHA-256 hash — we literally cannot tell you what the plaintext was if you lose it. Revoke and rotate.

​
Scopes

ScopeGrants
deals:readGET /v1/deals
deals:writePOST /v1/deals/events
earnings:readGET /v1/earnings, GET /v1/earnings/:id
plans:readGET /v1/plans, GET /v1/plans/:id
Keys without the required scope for a given endpoint get a 403 Forbidden with {"error":"forbidden","reason":"missing scope: <scope>"}. Grant the minimum set.

​
The request header

Authorization: Bearer oqp_<64-hex-chars>
A missing or malformed header returns 401 Unauthenticated. A revoked or unknown key returns 401 Invalid Key.

​
Rotation

Rotate regularly. Workflow:
  1. Create a new key with the same scopes.
  2. Deploy the new key to your callers.
  3. Verify traffic is flowing via the new key (its last_used_at updates on every successful call).
  4. Revoke the old key in the admin UI.
Revoked keys stop working immediately — there’s no grace period, so make sure step 3 completes before step 4.

​
Observability

Every authenticated request:
  • Updates last_used_at on the key (fire-and-forget, so it doesn’t block the response).
  • Emits an audit entry visible in the OpenQuota admin’s audit log.
  • Returns X-RateLimit-* response headers (see Rate limits).

​
Why Bearer and not signed requests?

OpenQuota favors simple integration. Bearer tokens over HTTPS are sufficient for the threat model (stolen key = revoke key). We use HMAC signing for outbound webhooks where we have to prove authenticity to you — see Webhooks.