Skip to main content

​
API keys

The Sorraia API authenticates with API keys. Pass your key as a Bearer token on every request:
Keys are prefixed sor_live_ followed by 43 random characters. They’re issued in the dashboard under Settings → Integrations (the Programmatic API access section) and shown in plaintext exactly once — only a hash is stored, so Sorraia can never show you the key again. API keys are included on every paid plan. A key is scoped to the account that created it (your personal account or your organization) and can only read or write that account’s data.

​
Scopes

Each key carries a set of scopes that gate which endpoints it can reach. New keys default to read-only; grant write scopes explicitly when you create the key. A request to an endpoint your key isn’t scoped for returns HTTP 403 with { "error": "Insufficient scope", "code": "insufficient_scope", "required": "<scope>" }.

​
Errors

Authentication failures return HTTP 401 with a consistent shape:
You’ll get this when the key is missing, malformed, revoked, or expired.

​
Plan (402)

API access is included on every paid plan. A valid key whose account is on the Free plan receives HTTP 402:
Upgrading lifts it on the next request; keys are never revoked. DELETE /webhooks/{id} (unsubscribe) always works. A key that is missing, malformed, revoked or expired still gets the 401 above first.

​
Rotation & security

Treat API keys like passwords. Never commit them to git, embed them in client-side code, or paste them into shared docs.
  • Store keys in environment variables or a secrets manager — never in source control.
  • Rotate periodically (quarterly is a reasonable cadence). Create the new key, deploy it, then revoke the old one — there’s no downtime because both work until you revoke.
  • Revoke immediately if a key is exposed. Revocation is instant: in the dashboard, click Revoke on the key. Any integration using it stops working at once.
  • Use separate keys per integration so you can revoke one without disrupting the others, and so usage is attributable.