Authentication

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

For the integration recipe (creating a token, making your first call, rotating), see Authenticate. This page is the contract reference.

Audience

A token is issued for one of three audiences:

audience	Where it works
service	Public API (/v1/*) — backend-to-API. Most common.
customer	Public API (/v1/*) — read-only on the customer’s own data.
admin	Admin API (/v1/admin/*) and Public API.

The Public API accepts all three audiences; the Admin API accepts only admin.

Token format

sk_<env>_<32 random chars>

Prefix	Environment	Base URL
sk_sandbox_	Sandbox	https://api.sandbox.paylera.io
sk_live_	Live	https://api.paylera.io

A token is bound to one tenant and one environment. Cross-environment use returns 401 auth.wrong_environment.

Scopes

Tokens carry one or more scopes. Endpoints declare the scope they require; the API rejects calls whose token lacks it.

catalog:read         catalog:write
customers:read       customers:write
subscriptions:read   subscriptions:write
invoices:read        invoices:write
payments:read        payments:write
payments:refund
wallets:read         wallets:write
webhooks:read        webhooks:write
admin:read           admin:write
*                    (wildcard — every scope)

The dashboard’s token UI shows which scopes each endpoint needs. Scope to the smallest set required.

AAL2

Some endpoints — rotate provider secret, void invoice, cancel payment, issue manual credit note — require AAL2 (a second authentication factor: TOTP or WebAuthn). The token must carry an aal: 2 claim, asserted at issue time when the operator stepped up.

Tokens minted for non-interactive service use cannot satisfy AAL2. Operations behind AAL2 are operator-only by design — perform them through the dashboard or surface them to operators in your own internal tools that proxy through the Admin API with operator identity.

A 403 with problem: auth.aal2_required is the signal.

Acting on behalf of an operator

For backend services that expose admin functionality to your operators (your own internal tools), pass the operator’s identity:

X-Paylera-Acting-As: actor_…

The audit log records both the service token and the acting actor. If the action requires AAL2, the operator’s most recent AAL2 timestamp must be within the configured window (default: 30 minutes). Otherwise 405 auth.aal2_step_up_required.

TLS

All requests must be HTTPS to a valid Paylera certificate. The API rejects HTTP at the load balancer; there is no port 80 redirect — your client must send HTTPS or fail.

Error envelope

Auth failures use the standard error envelope:

{
  "type": "https://errors.paylera.io/auth/invalid_token",
  "title": "Invalid token",
  "status": 401,
  "detail": "The token has been revoked.",
  "problem": "auth.invalid_token",
  "trace_id": "01H8…"
}

Common values for problem:

• auth.missing_token
• auth.invalid_token
• auth.expired_token
• auth.wrong_environment
• auth.scope_required
• auth.aal2_required
• auth.aal2_step_up_required

Rotation

Rotate a token via the dashboard or:

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

Returns a new secret in the response (only once). The old secret stays valid for 24 hours, then 401s.

Revocation

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

Effective immediately.