Authentication

Server-to-server integrations authenticate with an API key carrying a fixed set of scopes. Actions that require a person to be present are completed in the dashboard and are not included in the public OpenAPI document.

API key

Mint one on Settings → API keys (a session with api_keys:manage and a fresh second factor; a key cannot mint a key). The secret is returned once:

{ "id": "key_…", "key": "pehmen_test_…", "start": "pehmen_test_ab", "name": "staging-server",
  "environment": "test", "scopes": ["payments:write", "payments:read"], "expires_at": null }

Send it as x-api-key or Authorization: Bearer. The prefix names the environment: pehmen_test_, pehmen_live_.

Scopes

Fourteen permissions can be granted to a key:

payments:read, payments:write, refunds:write, orders:write, trust:read, trust:write, beneficiary_changes:request, payouts:write, cases:read, cases:write, webhooks:read, insights:read, policies:read, recon:read

A scope outside this set is 400 validation_failed with details: [{ invalid_scopes: [...] }].

Interactive-only actions

The eight interactive permissions are never grantable: connections:write, api_keys:manage, team:write, policies:publish, payouts:approve, payouts:release, beneficiary_changes:approve, entitlement:request.

{ "error": { "code": "forbidden",
  "message": "this action requires an interactive session with fresh two-factor verification (API keys cannot step up)" } }

These operations are deliberately absent from the public OpenAPI document. If a key attempts an interactive-only action, the API returns 403 forbidden.

Environment binding

A key can only touch its own environment. Naming the other in x-pehmen-environment returns 403 environment_mismatch. Create and revoke keys in the dashboard.