Authentication

API keys, environments, and request signing

Authentication

All REST API requests require a secret API key in the Authorization header. Keys are scoped to a workspace and environment (live or sandbox). The key environment must match the data you are reading or writing — sandbox keys cannot access live recovery attempts.

API key format

Keys are generated with a prefix that encodes environment and type, followed by 48 hex characters of entropy. Only the secret key (_sk_) may be used for server-side API calls.

  • decl_live_sk_<48 hex chars> — production secret
  • decl_live_pk_<48 hex chars> — production publishable (client SDK init only)
  • decl_sandbox_sk_<48 hex chars> — sandbox secret
  • decl_sandbox_pk_<48 hex chars> — sandbox publishable

Request headers

http
Authorization: Bearer decl_live_sk_your_secret_key
Content-Type: application/json
Accept: application/json

The Events edge function also accepts the raw token via the apikey header, but Authorization: Bearer is recommended for all integrations.

Base URL

Production API host: https://app.declined.io/api. The REST surface is versioned under /api/v1 (for example https://app.declined.io/api/api/v1/events).

Official SDKs take a baseUrl of https://app.declined.io/api/api — they append /v1/… themselves. Do not set baseUrl to https://app.declined.io/api/api/v1 or paths will be duplicated.

For local development against the web app proxy, set your SDK baseUrl to your app origin with the /api prefix (e.g. http://localhost:3000/api) only if your deployment exposes those routes.

Creating and rotating keys

Generate keys from the dashboard → Webhooks & SDK → API Keys. Name keys by integration (e.g. "Production billing worker") so audit logs remain traceable. Revoked keys return 401 immediately; allow a overlap window when rotating.

Team permissions

Only workspace members with the Access API keys permission can create or revoke keys. API requests themselves do not carry user identity — the key determines workspace and environment scope.

Error responses

json
{
  "error": "Invalid or missing API key"
}

Malformed JSON returns 400. Validation failures on event payloads return 422 with a descriptive message.