API keys

Every request to the Tokeflow API authenticates with an API key — a credential bound to exactly one entity (an organization or one of its merchants) and to an explicit list of scopes. The endpoints on this page manage those keys programmatically: create a key with least-privilege scopes, list what exists, pause a key temporarily, and revoke it for good. Everything the Tokeflow Dashboard does with keys, your backend can automate — useful for onboarding flows that mint a key per merchant, and for scheduled credential rotation.

Keys come in two types. Secret keys (sk_…) grant server-side access and are sent in the Authorization: Bearer header; public keys (pk_…) are client-safe and restricted to the scopes 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.

Key lifecycle and rotation

When rotating, always create and deploy the replacement key before revoking the old one — revocation takes effect immediately, and any service still holding the old key starts receiving 401 authentication_error.

The API key object

Returned by every endpoint on this page. The creation response additionally carries api_key — the full secret — one time only.

Endpoints

GET/api/v1/api-keys

Returns a paginated list of API keys. Organizations can filter by entity_type and entity_id to view the keys of a specific merchant.

Query parameters

Example request

curl -G https://api.tokeflow.com/api/v1/api-keys \
  -H "Authorization: Bearer sk_live_org_2b7e91c4a0f53d68" \
  --data-urlencode "entity_type=merchant" \
  --data-urlencode "entity_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",
      "key_hash": "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3"
    },
    {
      "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",
      "key_hash": "3c363836cf4e16666669a25da280a1865c2d2874"
    }
  ],
  "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. See Pagination & filtering for the general pattern.

POST/api/v1/api-keys

Creates an API key for an organization or merchant. The response is the only place the full key (api_key) is ever returned.

Request fields

Response codes

Example request

curl -X POST https://api.tokeflow.com/api/v1/api-keys \
  -H "Authorization: Bearer sk_live_org_2b7e91c4a0f53d68" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "merchant",
    "entity_id": "mrc_8a3f12d9",
    "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/api-keys/scopes

Returns all valid scopes that can be assigned to API keys. Filter by entity_type (organization/merchant) and/or key_type (secret/public) to narrow the results to what a given key could actually carry — useful for validating a scopes list before calling POST /api-keys, or for building a key-creation form.

Query parameters

Example request

curl -G https://api.tokeflow.com/api/v1/api-keys/scopes \
  -H "Authorization: Bearer sk_live_org_2b7e91c4a0f53d68" \
  --data-urlencode "entity_type=organization" \
  --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": [
    "org:*",
    "org:transactions:*"
  ]
}

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

PATCH/api/v1/api-keys/:id

Updates a key's activation state. Set is_active to false to deactivate the key — requests using it start failing with 401 authentication_error immediately — or back to true to reactivate it. Use this as the reversible switch; use revoke when the key should never come back.

Request fields

Example request

curl -X PATCH https://api.tokeflow.com/api/v1/api-keys/ak_9f2e6c81 \
  -H "Authorization: Bearer sk_live_org_2b7e91c4a0f53d68" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

Example response — 200 OK

{
  "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": false,
  "expires_at": null,
  "last_used_at": "2026-08-11T18:22:04.000Z",
  "created_at": "2026-08-12T14:03:00.000Z",
  "key_hash": "6dcd4ce23d88e2ee9568ba546c007c63d9131c1b"
}

A 403 is returned if the key exists but does not belong to your entity, and a 404 if it does not exist.

POST/api/v1/api-keys/:id/revoke

Revokes an API key, deactivating it permanently. Revocation takes effect immediately: any request presenting the revoked key fails with 401 authentication_error. Unlike a PATCH deactivation, a revoked key is retired for good — if the workload still needs access, create a replacement key first.

Example request

curl -X POST https://api.tokeflow.com/api/v1/api-keys/ak_9f2e6c81/revoke \
  -H "Authorization: Bearer sk_live_org_2b7e91c4a0f53d68"

Example response — 200 OK

{
  "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": false,
  "expires_at": null,
  "last_used_at": "2026-08-11T18:22:04.000Z",
  "created_at": "2026-08-12T14:03:00.000Z",
  "key_hash": "6dcd4ce23d88e2ee9568ba546c007c63d9131c1b"
}

A 403 is returned if the key does not belong to your entity, and a 404 if it does not exist.

Errors

Errors use the standard envelope. The most common cases for this resource:

See Errors for the full envelope and type catalog.

Related

• Authentication — the Bearer scheme, scopes, and key anatomy.
• Environments & API keys — key lifecycle, storage, and rotation practices.
• Pagination & filtering — list conventions used by the list endpoint.
• Errors — the standard error envelope.