Skip to main content

​
Overview

Commerce API keys authenticate Commerce requests. Keys are scope-based and are prefixed with ck_.... Use them as x-commerce-api-key: ck_... on Commerce endpoints. For most teams, the easiest path is to manage keys in the Dashboard (login required): .

​
Authentication

Key management endpoints require a Dashboard JWT:
  • Authorization: Bearer <jwt>

​
Request

Endpoints:
  • GET /api/v1/api-keys?scope=commerce (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":"Commerce key (prod)","scope":"commerce","expires_at":null}'

​
Response

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

​
Errors

  • 401 missing/invalid bearer token
  • 400 invalid scope or request body
  • 403 policy limit reached (for example, max active keys per scope)
  • 404 key not found (revoke)

​
Examples

Use the created key on Commerce endpoints: 
BASE_URL=${PEPAY_API_URL}

curl "$BASE_URL/api/commerce/status" \
  -H "x-commerce-api-key: ck_..."
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>" \
  -H "Content-Type: application/json" \
  -d '{}'
Next: Commerce status