API Keys

API Keys provide a simpler alternative to OAuth 2.0 for authenticating with the API Gateway. Instead of managing tokens, you use a single API key that is passed in every request.

What is an API Key?

An API Key is a unique credential that identifies your application and grants access to API resources. API keys are:

• Long-lived — They remain valid until manually disabled
• Self-contained — No token exchange is required; use the key directly
• Scoped — Permissions are defined when the key is created

API Key Format

API keys follow the format apk_<alphanumeric> and look like:

apk_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz

⚠️

Security Note: API keys should be treated like passwords. Store them securely and never expose them in client-side code or version control.

Creating an API Key

API keys are created through the API Gateway's API Keys endpoint. You need an existing OAuth access token to create an API key, and can only create API keys for scopes to which you have access. Usually, this will be done using the My Buckaroo portal. The available scopes depend on your role in the organization and will be shown in the UI.

Request

Endpoint: POST /v1/apikeys

Headers:

Authorization: Bearer <access_token>
Content-Type: application/json

Request Body:

{
  "name": "my-integration-key",
  "scopes": "sale:read sale:write transaction:read"
}

Response

HTTP Status: 201 Created

{
  "id": "apk_abcd1234efgh5678",
  "key": "apk_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz",
  "name": "my-integration-key",
  "maskedApiKey": "apk_abc***xyz",
  "status": "Active",
  "scopes": "sale:read sale:write transaction:read",
  "createdAt": "2024-05-16T10:30:00Z",
  "_links": {
    "self": {
      "href": "/v1/apikeys/apk_abcd1234efgh5678",
      "method": "GET"
    }
  }
}

📘

Unlike client secrets and refresh tokens, the key field containing the full API key value can be retrieved after the initial creation if lost using the PATCH /v1/apikeys/{id}/decrypt endpoint.

Using API Keys

To authenticate using an API key, include it in the X-API-KEY header with every request:

X-API-KEY: <your_api_key>