Authentication

Every digid pay API request is authenticated with an API key pair scoped to your merchant account and to one mode (sandbox or live).

Key pairs

Key	Prefix	Use
Publishable key	pk_live_… / pk_sandbox_…	Client-safe: identifies your account, renders Secure Fields, never authorises server actions.
Secret key	sk_live_… / sk_sandbox_…	Server-only: authenticates API requests. Shown once at creation.

Authentication:

Authorization: Bearer sk_live_...

Send the key as a Bearer token. Everything over HTTPS; the key is the credential — guard it like a password.

Browser-UA rejection (FR-7)

Secret keys are server-side only. If a request carrying a secret key originates from a browser-like context (a browser User-Agent), digid pay rejects it with a specific error code and alerts the merchant in the dashboard, where one click rotates the key:

{ "error": { "type": "authentication_error", "code": "secret_key_from_browser", "message": "Secret keys cannot be used from browser contexts.", "param": null } }

Use the publishable key in client code; keep the secret key on your backend.

Create keys

You can create keys in the dashboard or over the API:

curl https://api.digid.cc/v1/keys \
  -u sk_live_...: \
  -H "Content-Type: application/json" \
  -d '{ "label": "production-webhook-backend", "mode": "live" }'

{
  "publishable_key": "pk_live_...",
  "secret_key": "sk_live_...",
  "note": "The secret key is shown only once."
}

The secret is shown exactly once and stored hashed-at-rest (compare-on-use, never retrievable again). Store it immediately in your secret manager.

List keys

Key metadata (label, mode, prefix, last used, created) is always retrievable; secret values are not:

curl https://api.digid.cc/v1/keys -u sk_live_...:

Rotate

Rotation issues a new secret and retires the old one. Any key you identify as exposed should be rotated immediately:

curl -X POST https://api.digid.cc/v1/keys/key_.../rotate \
  -u sk_live_...: \
  -H "Idempotency-Key: rotate-key-17" \
  -H "Content-Type: application/json"

The response contains the new secret_key once. Rotate the same key again to issue another pair; a rotated-out secret stops authenticating.

Revoke

Revocation is instant — a revoked key fails within seconds across API and webhook surfaces:

curl -X DELETE https://api.digid.cc/v1/keys/key_... -u sk_live_...:

Per-key scopes

Keys may carry optional scope labels restricting what they can do (for example a read-only key for monitoring). Scope enforcement is part of the facade contract; keys without scopes are unrestricted for their mode.

Misuse detection

digid pay watches for obvious secret-key leakage signals (browser-context use, suspicious geography, unexpected bursts) and surfaces an alert in the dashboard with a one-click rotate action. Treat any alert as an active exposure: rotate, then investigate.

HMAC & integrity

Key material never travels except as the Bearer credential over TLS. Webhook payloads are additionally signed per merchant with HMAC-SHA256 (see Webhooks); if you need request signing on the API itself, the pattern mirrors the webhook scheme — contact support before relying on it, since it is not yet part of the documented contract.

Further reading

• Errors — authentication_error vs invalid_request_error.
• Security — key handling runbook for operators.
• Rate limits — per-key limits.