Skip to main content

​
Overview

Merchant API keys authenticate server-to-server requests using the x-api-key header.

​
Authentication

These endpoints require a dashboard JWT:
  • Authorization: Bearer <jwt>

​
Request

Endpoints:
  • GET /api/v1/api-keys?scope=merchant (list)
  • POST /api/v1/api-keys (create)
  • POST /api/v1/api-keys/{keyId}/revoke (revoke)
Example (create): 
BASE_URL=${PEPAY_API_URL}

curl -X POST "$BASE_URL/api/v1/api-keys" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"name":"production-server","scope":"merchant","expires_at":null}'

​
Response

Example (created key — save it now, it is only returned on creation): 
{
  "key_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "production-server",
  "scope": "merchant",
  "api_key": "pk_0123456789abcdef...",
  "expires_at": null
}
Example (list keys — metadata only): 
[
  {
    "key_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "production-server",
    "scope": "merchant",
    "status": "active",
    "expires_at": null,
    "last_used_at": null,
    "created_at": "2025-12-21T12:34:56.000Z",
    "revoked_at": null,
    "revoked_reason": null
  }
]
Example (revoke): 
{ "message": "API key revoked successfully" }

​
Errors

  • 401/403 missing/invalid bearer token
  • 400 validation error (invalid name/expires)
  • 403 policy limit reached (for example, max active keys per scope)
  • 404 key not found (revoke)

​
Examples

Example (revoke): 
BASE_URL=${PEPAY_API_URL}

curl -X POST "$BASE_URL/api/v1/api-keys/550e8400-e29b-41d4-a716-446655440000/revoke" \
  -H "Authorization: Bearer <jwt>"
Next: Access