Skip to main content
Every request carries a bearer token. Which kind depends on who you are.

Secret keys (server-to-server)

The common case. Pass your secret key as a bearer token:
  • The prefix selects the mode: sk_test_… → sandbox, sk_live_… → live.
  • Keys are hashed at rest — Duro can’t show you a key again after creation, so store it securely.
  • Keys carry full scope within their tenant. Treat a live secret key like a password.
  • A publishable key (pk_…) is safe to expose in the browser/SDK; it can start checkout sessions but can’t read or mutate data.
Never ship a sk_ key to a browser or mobile app. Use the publishable key and the inline SDK client-side; keep secrets on your server.

OAuth2 (client credentials)

For platforms acting on a tenant’s behalf, exchange a client id/secret for a short-lived token:
Returns an access token valid for 60 minutes. Use it exactly like a secret key (Authorization: Bearer <token>). The client id prefix carries the mode.

Customer identity tokens

The customer-facing endpoints (/identity/me, /portal/*) use a token issued after a customer verifies their phone over WhatsApp: Identity tokens are scoped to a person, not a tenant — they resolve to a CustomerIdentity and are rejected by the merchant /v1 API. See Universal Identity.

Errors

A missing or invalid credential returns 401. An authenticated request that lacks the required permission returns 403. See Errors.