Authenticate

Every Paylera API call carries an Authorization: Bearer <token> header. Tokens are minted on the dashboard and scoped per use case.

Audiences

A token is issued for one of three audiences:

Audience	Use it for
service	Backend-to-Paylera traffic from your servers. The most common audience.
customer	Tokens issued to end-users for read-only access to their own data (rare; usually you proxy through your backend).
admin	Operator console use only. Required for the AdminApi (/v1/admin/*).

You’ll start with one or more service tokens. Create them in Developers → API tokens on the dashboard.

Token format

sk_<env>_<random>

Env prefix	Meaning
sk_sandbox_	Works against https://api.sandbox.paylera.io only.
sk_live_	Works against https://api.paylera.io only.

Sending a sandbox token to live (or vice-versa) returns 401 with problem: auth.wrong_environment.

Making a call

curl https://api.sandbox.paylera.io/v1/customers \
  -H "Authorization: Bearer $PAYLERA_KEY"

That’s the entire authentication contract. There’s no signing, no nonce, no clock skew. The token is the credential; HTTPS is the transport.

Scopes

A token carries one or more scopes:

catalog:read
catalog:write
customers:read
customers:write
subscriptions:read
subscriptions:write
payments:read
payments:write
payments:refund
webhooks:read
webhooks:write
*               (wildcard — all scopes)

Scope a token to the smallest set of permissions it needs. The dashboard’s token UI shows the scopes each endpoint requires.

Per-request idempotency

For any POST that creates a resource or moves money, include an Idempotency-Key header — see Idempotency. Without it, the request is rejected:

{
  "type": "https://errors.paylera.io/idempotency/required",
  "title": "Idempotency-Key required",
  "status": 400,
  "problem": "idempotency.required"
}

Versioning

Pin the API version your code expects:

curl https://api.paylera.io/v1/customers \
  -H "Authorization: Bearer $PAYLERA_KEY" \
  -H "Paylera-Version: 2026-04-01"

If you don’t send a version header, the API uses the version that was default at the time your token was created. New tokens get the current default. See Versioning.

Service-to-service traffic

For backend services consuming Paylera webhooks or driving the API, issue one service token per service. Don’t reuse human-operator tokens.

When a backend service makes an admin-style change on behalf of a real operator (e.g., your internal admin tool), pass the operator’s identity:

X-Paylera-Acting-As: actor_…

The acting_as actor must exist in your tenant’s actor registry (create them via Admin API → actors). The audit log records both the service token and the acting actor.

Rotating a token

POST /v1/admin/api-tokens/{id}/rotate

Returns a new secret in the response (only once). The old secret keeps working for 24 hours, then 401s. Rotate on a schedule and on every suspected leak.

Revoking

DELETE /v1/admin/api-tokens/{id}

Immediate. The next request with the revoked token gets 401.

Common 401s

problem	Cause
auth.missing_token	No Authorization header.
auth.invalid_token	Token doesn’t exist or was revoked.
auth.expired_token	Rotated and the grace period elapsed.
auth.wrong_environment	Sandbox token on live URL or vice-versa.
auth.scope_required	The endpoint requires a scope this token doesn’t have.
auth.aal2_required	Endpoint requires AAL2; the token’s principal hasn’t asserted it.