Skip to main content
API keys allow merchants to authenticate server-to-server integrations without using Bearer tokens. Each key consists of a key ID and a secret.

​
Create API Key

​
Authorization
string
required
Bearer token.
POST /v1/api-keys

​
Request Body

​
name
string
required
A descriptive label for the API key (e.g., Production Server).
​
permissions
string[]
List of permission scopes. Defaults to all permissions. Options: payments:read, payments:write, settlements:read, settlements:write, webhooks:manage.

​
Example Request

{
  "name": "Production Server",
  "permissions": ["payments:read", "payments:write", "webhooks:manage"]
}

​
Example Response (201)

{
  "id": "key_abc123",
  "name": "Production Server",
  "apiKey": "opk_live_a1b2c3d4e5f6",
  "apiSecret": "ops_live_x9y8z7w6v5u4",
  "permissions": ["payments:read", "payments:write", "webhooks:manage"],
  "createdAt": "2026-03-26T10:00:00Z"
}
The apiSecret is returned only once at creation time. Store it securely — it cannot be retrieved again.

​
List API Keys

GET /v1/api-keys
Returns all API keys for the authenticated merchant. Secrets are not included in the response.

​
Example Response (200)

{
  "data": [
    {
      "id": "key_abc123",
      "name": "Production Server",
      "apiKey": "opk_live_a1b2c3d4e5f6",
      "permissions": ["payments:read", "payments:write", "webhooks:manage"],
      "lastUsedAt": "2026-03-26T11:30:00Z",
      "createdAt": "2026-03-26T10:00:00Z"
    },
    {
      "id": "key_def456",
      "name": "Staging Server",
      "apiKey": "opk_test_g7h8i9j0k1l2",
      "permissions": ["payments:read"],
      "lastUsedAt": null,
      "createdAt": "2026-03-25T08:00:00Z"
    }
  ]
}

​
Revoke API Key

DELETE /v1/api-keys/{id}
Permanently revokes an API key. This action cannot be undone.

​
Path Parameters

​
id
string
required
The API key identifier (e.g., key_abc123).

​
Example Response (200)

{
  "message": "API key revoked successfully"
}

​
Error Responses

404 Not Found
{
  "error": {
    "code": "NOT_FOUND",
    "message": "API key not found"
  }
}