Authentication

Every request is authenticated with an API key sent as a bearer token.

Authorization: Bearer olp_live_xxxxxxxxxxxxxxxxxxxxxxxx

There is no other credential to manage: no client secret, no OAuth flow, no session.

Sandbox and live keys#

	Sandbox key	Live key
Prefix	`olp_test_`	`olp_live_`
Real money	Never	Yes
Business verification needed	No	Yes
Payments and payment links	Confirmed on a sandbox page	Processed by the payment provider
Payouts	Rejected (`400`)	Allowed
Data	Separate: sandbox objects never appear with a live key, and the reverse

The key itself decides the environment. The base URL is the same. Use a sandbox key everywhere except production.

Creating a key#

Developers, then API keys, then Create key in the dashboard. Only the business owner and admins can create keys. The full key is shown once. Olympus Pay stores only a hash, so a lost key cannot be recovered, only replaced.

Scopes#

Give each key only what its integration needs. A request outside a key's scopes returns 403 with code permission_denied.

Scope	Allows
`payment_links:write`	`POST /payment-links`
`qr_codes:write`	`POST /qr-codes`
`payments:read`	`GET /payments`, `GET /payments/{id}`
`payments:cancel`	`POST /payments/{id}/cancel`
`refunds:create_full`	`POST /payments/{id}/refund` without an amount
`refunds:create_partial`	`POST /payments/{id}/refund` with an amount
`payouts:create`	`POST /payouts`
`payouts:read`	`GET /payouts`
`payouts:cancel`	`POST /payouts/{id}/cancel`
`settlements:read`	`GET /settlements`
`reports:export`	CSV export of settlements (in addition to `settlements:read`)
`recipients:write`, `recipients:read`, `recipients:verify`, `recipients:disable`	Split recipients
`splits:assign`	Attaching a split recipient to a link or QR code
`webhooks:manage`, `webhooks:read_logs`, `webhooks:retry`	Webhook endpoints and deliveries
`account:read`, `kyc:read`, `kyc:write`	Business profile and verification

A key created with no scopes has full access. Prefer explicit scopes.

Hardening a key#

On the key's page you can also set:

IP allowlist. Requests from any other address get 401.
Expiry date. After it the key stops working.
Redirect domains. A returnUrl on a payment link or QR code must be on one of these domains.

Rotation and revocation#

Rotate replaces the key's secret in place: the key keeps its identity, scopes and allowlist, and the old secret stops working immediately. The new secret is shown once. Have the new value ready to deploy before you rotate. Rotate on a schedule and whenever someone with access leaves.
Revoke disables a key immediately and cannot be undone.
The key's page shows recent requests with their status codes and the IP address each came from. Check it after any suspected leak.

If a key is exposed (committed to a repository, pasted in a chat, logged), revoke it first and investigate afterwards.

Authentication errors#

Status	Code	Meaning
`401`	`authentication_failed`	Missing, malformed, unknown, revoked or expired key, or a request from an address outside the key's allowlist
`403`	`permission_denied`	The key is valid but lacks the scope, or the business is not yet verified for a live operation
`429`	`rate_limited`	Too many requests: see Rate limits

Every error body carries a request_id: see Errors.