Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.dubupay.com/llms.txt

Use this file to discover all available pages before exploring further.

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:
EnvironmentFormat
Livedubu_sk_live_<32 random characters>
Sandboxdubu_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
​
name
string
required
A human-readable label for this key. Use something descriptive like "production-backend" or "staging-worker". Maximum 100 characters.
​
environment
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"
  }'
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
​
id
string
required
UUID of the API key. Use this in revoke and delete requests.
​
name
string
required
The label you assigned to this key.
​
key_prefix
string
required
First 20 characters of the key. Safe to display in logs and list views.
​
environment
string
required
"sandbox" or "live".
​
created_at
string
required
ISO 8601 timestamp of when the key was created.
​
key
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'
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)
​
id
string
required
UUID of the API key.
​
name
string
required
Human-readable label.
​
key_prefix
string
required
First 20 characters of the key for identification.
​
environment
string
required
"sandbox" or "live".
​
is_active
boolean
required
true if the key can be used to authenticate requests. false if the key has been revoked.
​
last_used_at
string
ISO 8601 timestamp of the most recent authenticated request using this key. null if the key has never been used.
​
created_at
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.
​
id
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'
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.
​
id
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'
Example response 
{
  "success": true,
  "message": "API key deleted"
}

​
Security best practices

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.
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.
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.
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.
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.

​
Next steps

Authentication overview

Compare JWT bearer tokens and API keys, and learn how to refresh tokens.

Quickstart

Walk through registering, creating a key, and issuing a virtual bank account.