Create and manage Dubu Pay API keys

API keys are the recommended authentication method for server-side integrations. Unlike JWT tokens, they do not expire automatically, which makes them well-suited for background services, cron jobs, and backend applications that make API calls without an interactive login flow. All API key endpoints require an authenticated request — use either a bearer token or an existing API key.

The full API key secret is shown only once, immediately after creation. If you lose it, you must delete the key and create a new one. Store keys in a secret manager or environment variable as soon as you receive them.

Key format

Dubu Pay API keys follow a predictable format so they are easy to identify and can be detected by secret-scanning tools:

Environment	Format
Live	`dubu_sk_live_<32 random characters>`
Sandbox	`dubu_sk_test_<32 random characters>`

After creation, only the first 20 characters (key_prefix) are stored and returned by list endpoints. Use the prefix to identify which key you are viewing without exposing the secret.

Create an API key

POST /api-keys Creates a new API key scoped to your merchant account. The response includes the full plaintext key field — this is the only time it is returned. Request body

string

required

A human-readable label for this key. Use something descriptive like "production-backend" or "staging-worker". Maximum 100 characters.

string

"sandbox" or "live". Defaults to "sandbox". Sandbox keys carry the prefix dubu_sk_test_; live keys carry dubu_sk_live_.

curl --request POST \
  --url https://api.dubupay.com/api/v1/api-keys \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "production-backend",
    "environment": "live"
  }'

const response = await fetch('https://api.dubupay.com/api/v1/api-keys', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${access_token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'production-backend',
    environment: 'live',
  }),
});
const { data } = await response.json();
// data.key is the full secret — store it now
console.log(data.key);

Example response

{
  "success": true,
  "data": {
    "id": "3f7a1c2e-84d0-4b1a-9c6f-2e5d8a0b7f3c",
    "name": "production-backend",
    "key_prefix": "dubu_sk_live_AbCdEf",
    "environment": "live",
    "created_at": "2025-09-01T10:05:00.000Z",
    "key": "dubu_sk_live_AbCdEfGhIjKlMnOpQrStUvWxYz012345"
  }
}

Response fields

string

required

UUID of the API key. Use this in revoke and delete requests.

string

required

The label you assigned to this key.

string

required

First 20 characters of the key. Safe to display in logs and list views.

string

required

"sandbox" or "live".

string

required

ISO 8601 timestamp of when the key was created.

string

required

The full plaintext API key. Returned only in this response. Store it immediately.

List API keys

GET /api-keys Returns all API keys associated with your merchant account. The key secret is never included in list responses — only the key_prefix is returned for identification.

curl --request GET \
  --url https://api.dubupay.com/api/v1/api-keys \
  --header 'X-Api-Key: dubu_sk_live_AbCdEfGhIjKlMnOpQrStUvWxYz012345'

const response = await fetch('https://api.dubupay.com/api/v1/api-keys', {
  headers: {
    'X-Api-Key': process.env.DUBU_API_KEY,
  },
});
const { data } = await response.json();

Example response

{
  "success": true,
  "data": [
    {
      "id": "3f7a1c2e-84d0-4b1a-9c6f-2e5d8a0b7f3c",
      "name": "production-backend",
      "key_prefix": "dubu_sk_live_AbCdEf",
      "environment": "live",
      "is_active": true,
      "last_used_at": "2025-09-01T14:22:00.000Z",
      "created_at": "2025-09-01T10:05:00.000Z"
    },
    {
      "id": "a1b2c3d4-...",
      "name": "staging-worker",
      "key_prefix": "dubu_sk_test_XyZaBc",
      "environment": "sandbox",
      "is_active": false,
      "last_used_at": null,
      "created_at": "2025-08-15T08:00:00.000Z"
    }
  ]
}

Response fields (per key)

string

required

UUID of the API key.

string

required

Human-readable label.

string

required

First 20 characters of the key for identification.

string

required

"sandbox" or "live".

boolean

required

true if the key can be used to authenticate requests. false if the key has been revoked.

string

ISO 8601 timestamp of the most recent authenticated request using this key. null if the key has never been used.

string

required

ISO 8601 timestamp of when the key was created.

Revoke an API key

PATCH /api-keys/:id/revoke Revokes the key, setting is_active to false. Revoked keys are rejected on all subsequent requests but remain visible in the key list. Use revoke when you want to disable a key temporarily or audit it before permanent deletion.

string

required

UUID of the API key to revoke.

curl --request PATCH \
  --url https://api.dubupay.com/api/v1/api-keys/3f7a1c2e-84d0-4b1a-9c6f-2e5d8a0b7f3c/revoke \
  --header 'X-Api-Key: dubu_sk_live_AbCdEfGhIjKlMnOpQrStUvWxYz012345'

const keyId = '3f7a1c2e-84d0-4b1a-9c6f-2e5d8a0b7f3c';
const response = await fetch(
  `https://api.dubupay.com/api/v1/api-keys/${keyId}/revoke`,
  {
    method: 'PATCH',
    headers: { 'X-Api-Key': process.env.DUBU_API_KEY },
  }
);
const result = await response.json();

Example response

{
  "success": true,
  "message": "API key revoked"
}

Delete an API key

DELETE /api-keys/:id Permanently removes the API key from your account. This action cannot be undone. Use deletion when you are certain you no longer need the key record.

string

required

UUID of the API key to delete.

curl --request DELETE \
  --url https://api.dubupay.com/api/v1/api-keys/3f7a1c2e-84d0-4b1a-9c6f-2e5d8a0b7f3c \
  --header 'X-Api-Key: dubu_sk_live_AbCdEfGhIjKlMnOpQrStUvWxYz012345'

const keyId = '3f7a1c2e-84d0-4b1a-9c6f-2e5d8a0b7f3c';
const response = await fetch(
  `https://api.dubupay.com/api/v1/api-keys/${keyId}`,
  {
    method: 'DELETE',
    headers: { 'X-Api-Key': process.env.DUBU_API_KEY },
  }
);
const result = await response.json();

Example response

{
  "success": true,
  "message": "API key deleted"
}

Security best practices

Store keys in environment variables or a secret manager

Never hard-code an API key in your source code. Use environment variables in local development (e.g. DUBU_API_KEY=dubu_sk_live_...) and a secrets manager such as AWS Secrets Manager, HashiCorp Vault, or your platform’s built-in secrets store in production.

Never expose keys in client-side code

API keys must only be used in server-side code. If a key appears in a browser, a mobile app binary, or a public repository, treat it as compromised and rotate it immediately.

Rotate keys regularly

Create a replacement key before revoking the existing one to avoid downtime. Aim to rotate live keys at least every 90 days, or immediately after any suspected exposure.

Use separate keys per environment and service

Create one key per environment (sandbox, live) and ideally one per service or deployment. This limits the blast radius of a compromised key and makes it easy to rotate without affecting other services.

Monitor last_used_at

Check the last_used_at field when listing keys. Keys that have never been used or that have been idle for an extended period are candidates for deletion.

Use a sandbox key (dubu_sk_test_...) during development and testing. Switch to a live key only in production deployments.

Get Started

Authentication

Core Concepts

Guides

Account & Security

Create and manage Dubu Pay API keys

Key format

Create an API key

List API keys

Revoke an API key

Delete an API key

Security best practices

Next steps

Authentication overview

Quickstart

​Key format

​Create an API key

​List API keys

​Revoke an API key

​Delete an API key

​Security best practices

​Next steps

Authentication overview

Quickstart

Key format

Create an API key

List API keys

Revoke an API key

Delete an API key

Security best practices

Next steps