Merchant API keys

These endpoints power the API keys screen of the Tokeflow Dashboard for a merchant: list the keys that exist, mint a new one, look up which scopes it may carry, and revoke a key that should no longer work. The keys they manage are the same sk_… (secret) and pk_… (public) credentials your integration presents to the public API — the Dashboard is simply the human-friendly way to manage them.

Secret keys grant server-side access and belong in a secrets manager; public keys are client-safe and restricted to what the Bridge SDK needs in the browser. See Authentication for the full model and Environments & API keys for how keys encode environment and entity in their prefix.

How the key screen flows

The scopes endpoint feeds the key-creation form: it returns only the scopes valid for this merchant and the chosen key type, so the user can never select a scope the key could not carry. After creation, the full key is never shown again — the list identifies each key by its key_prefix alone.

The API key object

Returned on creation; the list endpoint returns the same object without the creation-only api_key secret.

Endpoints

GET/api/v1/merchant/api-keys

Returns a paginated list of the merchant's API keys — the merchant is taken from the x-merchant-id header.

Query parameters

Example request

curl -G https://api.tokeflow.com/api/v1/merchant/api-keys \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20"

Example response — 200 OK

{
  "data": [
    {
      "id": "ak_9f2e6c81",
      "entity_type": "merchant",
      "entity_id": "mrc_8a3f12d9",
      "name": "Checkout service (production)",
      "key_prefix": "sk_live_mer_7d21",
      "scopes": ["transactions:read", "transactions:write"],
      "allowed_ips": ["203.0.113.10", "198.51.100.0/24"],
      "is_active": true,
      "expires_at": null,
      "last_used_at": "2026-08-11T18:22:04.000Z",
      "created_at": "2026-03-02T09:15:00.000Z"
    },
    {
      "id": "ak_5b0d3a47",
      "entity_type": "merchant",
      "entity_id": "mrc_8a3f12d9",
      "name": "Storefront widget",
      "key_prefix": "pk_live_mer_0c1d",
      "scopes": ["tokens:read"],
      "allowed_ips": null,
      "is_active": false,
      "expires_at": "2026-12-31T23:59:59.000Z",
      "last_used_at": "2026-07-30T10:41:52.000Z",
      "created_at": "2026-01-20T16:00:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 2,
    "total_pages": 1,
    "has_next": false,
    "has_prev": false
  }
}

data holds the keys for the current page and meta the pagination metadata — advance page while has_next is true. The full key is never included here; each key is identified by its non-secret key_prefix.

POST/api/v1/merchant/api-keys

Creates an API key for the merchant identified by x-merchant-id. The response is the only place the full key (api_key) is ever returned.

Request fields

Example request

curl -X POST https://api.tokeflow.com/api/v1/merchant/api-keys \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Checkout service (production)",
    "scopes": ["transactions:read", "transactions:write"],
    "allowed_ips": ["203.0.113.10", "198.51.100.0/24"],
    "key_type": "secret"
  }'

Example response — 201 Created

{
  "id": "ak_9f2e6c81",
  "entity_type": "merchant",
  "entity_id": "mrc_8a3f12d9",
  "name": "Checkout service (production)",
  "key_prefix": "sk_live_mer_7d21",
  "scopes": ["transactions:read", "transactions:write"],
  "allowed_ips": ["203.0.113.10", "198.51.100.0/24"],
  "is_active": true,
  "expires_at": null,
  "last_used_at": null,
  "created_at": "2026-08-12T14:03:00.000Z",
  "api_key": "sk_live_mer_7d21c39ab8e4f560",
  "key_hash": "6dcd4ce23d88e2ee9568ba546c007c63d9131c1b"
}

GET/api/v1/merchant/api-keys/scopes

Returns the scopes that can be assigned to this merchant's API keys. Org-only scopes are excluded. Filter by key_type to get the scopes valid for public or secret keys — this is what the Dashboard's key-creation form uses to populate its scope picker before calling POST /merchant/api-keys.

Query parameters

Example request

curl -G https://api.tokeflow.com/api/v1/merchant/api-keys/scopes \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  --data-urlencode "key_type=secret"

Example response — 200 OK (truncated)

{
  "scopes": [
    {
      "scope": "transactions:read",
      "description": "List and view transactions"
    },
    {
      "scope": "transactions:write",
      "description": "Create, capture, and refund transactions"
    },
    {
      "scope": "customers:read",
      "description": "List and view customers"
    }
  ],
  "wildcards": [
    "transactions:*",
    "customers:*"
  ]
}

Each item in scopes pairs the scope string with a human-readable description. wildcards lists the wildcard scope strings valid for this entity and key type — a wildcard grants every scope it covers, so reserve them for trusted, tightly-controlled services and prefer explicit scope lists everywhere else.

DELETE/api/v1/merchant/api-keys/:id

Revokes an API key permanently. Revocation takes effect immediately: any request presenting the revoked key fails authentication from that moment on. There is no undo — if the workload still needs access, create a replacement key first.

Path parameters

Example request

curl -X DELETE https://api.tokeflow.com/api/v1/merchant/api-keys/ak_9f2e6c81 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9"

Example response — 204 No Content

The response body is empty.

Errors

The most common cases for these endpoints:

See Errors for the general error format used across the API.

Related

• API keys (public API) — manage keys programmatically from your backend, including pause/reactivate.
• Authentication — the Bearer scheme, scopes, and key anatomy.
• Environments & API keys — key lifecycle, storage, and rotation practices.
• Errors — the standard error envelope.