tokeflow.com
DocumentationAPI ReferenceDashboardsSDKsChangelog

Organization API keys

Manage organization-level API keys from the Dashboard — create, list, inspect scopes, and revoke keys that act across every merchant in the org.

These endpoints back the organization's API-keys screen. An organization key (sk_live_org_… / pk_live_org_…) can act across every merchant in the org, naming the target merchant with merchant_id on each call — unlike a merchant key, which is scoped to one.

The full secret is shown only at creation; afterward a key is identified by its non-secret prefix. Revoking is immediate and permanent.

These endpoints power the Tokeflow Dashboard UI at the organization level. They are session-authenticated (JWT bearer) — the token comes from signing in to the Dashboard, not from an sk_/pk_ API key. Requests also carry the x-organization-id header, and the signed-in user must be a member of that organization.

The API key object

Returned by the list and retrieve endpoints on this page.

FieldTypeDescription
idstringUnique identifier for the API key.
entity_typestringType of entity (organization or merchant).
entity_idstringID of the entity.
namestringHuman-readable name for the API key.
key_prefixstringKey prefix for identification.
scopesarrayScopes/permissions for the API key.
allowed_ipsarray | nullAllowed IP addresses.
is_activebooleanWhether the API key is active.
expires_atstring | nullExpiration date. (ISO 8601 UTC).
last_used_atstring | nullLast time the key was used. (ISO 8601 UTC).
created_atstringCreation timestamp. (ISO 8601 UTC).
key_hashstring—

Endpoints

GET/api/v1/org/api-keys

Org

Auth: Dashboard session (JWT bearer). Organization membership required.

List API keys for merchant.

Query parameters

FieldTypeRequiredDescription
pagenumberNoPage number (1-indexed). Default 1, min 1.
limitnumberNoNumber of items per page. Default 20, min 1, max 100.

Example request

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

Example response — 200

{
  "data": [
    {
      "id": "obj_1a2b3c4d",
      "entity_type": "standard",
      "entity_id": "string",
      "name": "Acme Store",
      "key_prefix": "sk_live_mer_7d21",
      "scopes": [
        "string"
      ],
      "allowed_ips": [
        "203.0.113.10"
      ],
      "is_active": true,
      "expires_at": "2026-01-15T12:30:00.000Z",
      "last_used_at": "2026-01-15T12:30:00.000Z",
      "created_at": "2026-01-15T12:30:00.000Z",
      "key_hash": "sk_live_mer_7d21"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "total_pages": 3,
    "has_next": true,
    "has_prev": false
  }
}

POST/api/v1/org/api-keys

Org

Auth: Dashboard session (JWT bearer). Organization membership required.

Create a new API key for merchant.

Request fields

FieldTypeRequiredDescription
entity_typestringNoType of entity the API key belongs to. One of organization, merchant.
entity_idstringNoID of the entity (organization or merchant).
namestringYesHuman-readable name for the API key.
scopesarrayYes—
allowed_ipsarrayYes—
expires_atstringNoExpiration date for the API key (ISO 8601).
key_typestringNoType of API key - secret or public. One of secret, public.

Example request

curl -X POST https://api.tokeflow.com/api/v1/org/api-keys \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "merchant",
    "entity_id": "mrc_123",
    "name": "Production Key Store XPTO",
    "scopes": [
      [
        "transactions:write",
        "transactions:read"
      ]
    ],
    "allowed_ips": [
      [
        "1.2.3.4",
        "192.168.0.0/16",
        "2001:db8::/32"
      ]
    ],
    "expires_at": "2026-01-15T12:30:00.000Z",
    "key_type": "secret"
  }'

Example response — 201

{
  "id": "obj_1a2b3c4d",
  "entity_type": "standard",
  "entity_id": "string",
  "name": "Acme Store",
  "key_prefix": "sk_live_mer_7d21",
  "scopes": [
    "string"
  ],
  "allowed_ips": [
    "203.0.113.10"
  ],
  "is_active": true,
  "expires_at": "2026-01-15T12:30:00.000Z",
  "last_used_at": "2026-01-15T12:30:00.000Z",
  "created_at": "2026-01-15T12:30:00.000Z",
  "api_key": "sk_live_mer_98765...",
  "key_hash": "sk_live_mer_7d21"
}

GET/api/v1/org/api-keys/scopes

Org

Auth: Dashboard session (JWT bearer). Organization membership required.

Returns scopes that can be assigned to API keys. Filter by entity_type and/or key_type.

Query parameters

FieldTypeRequiredDescription
entity_typestringYes—
key_typestringYes—

Example request

curl -G https://api.tokeflow.com/api/v1/org/api-keys/scopes \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3" \
  --data-urlencode "entity_type=standard" \
  --data-urlencode "key_type=sk_live_mer_7d21"

GET/api/v1/org/api-keys/:id

Org

Auth: Dashboard session (JWT bearer). Organization membership required.

Get API key by ID.

Path parameters

FieldTypeRequiredDescription
idstringYesAPI Key ID

Example request

curl https://api.tokeflow.com/api/v1/org/api-keys/obj_1a2b3c4d \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3"

Example response — 200

{
  "id": "obj_1a2b3c4d",
  "entity_type": "standard",
  "entity_id": "string",
  "name": "Acme Store",
  "key_prefix": "sk_live_mer_7d21",
  "scopes": [
    "string"
  ],
  "allowed_ips": [
    "203.0.113.10"
  ],
  "is_active": true,
  "expires_at": "2026-01-15T12:30:00.000Z",
  "last_used_at": "2026-01-15T12:30:00.000Z",
  "created_at": "2026-01-15T12:30:00.000Z",
  "key_hash": "sk_live_mer_7d21"
}

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

Org

Auth: Dashboard session (JWT bearer). Organization membership required.

Update API key (activate/deactivate).

Path parameters

FieldTypeRequiredDescription
idstringYesAPI Key ID

Request fields

FieldTypeRequiredDescription
is_activebooleanNoWhether the API key is active.

Example request

curl -X PATCH https://api.tokeflow.com/api/v1/org/api-keys/obj_1a2b3c4d \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3" \
  -H "Content-Type: application/json" \
  -d '{
    "is_active": false
  }'

Example response — 200

{
  "id": "obj_1a2b3c4d",
  "entity_type": "standard",
  "entity_id": "string",
  "name": "Acme Store",
  "key_prefix": "sk_live_mer_7d21",
  "scopes": [
    "string"
  ],
  "allowed_ips": [
    "203.0.113.10"
  ],
  "is_active": true,
  "expires_at": "2026-01-15T12:30:00.000Z",
  "last_used_at": "2026-01-15T12:30:00.000Z",
  "created_at": "2026-01-15T12:30:00.000Z",
  "key_hash": "sk_live_mer_7d21"
}

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

Org

Auth: Dashboard session (JWT bearer). Organization membership required.

Revoke an API key (deactivates it).

Path parameters

FieldTypeRequiredDescription
idstringYesAPI Key ID

Example request

curl -X POST https://api.tokeflow.com/api/v1/org/api-keys/obj_1a2b3c4d/revoke \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3"

Example response — 200

{
  "id": "obj_1a2b3c4d",
  "entity_type": "standard",
  "entity_id": "string",
  "name": "Acme Store",
  "key_prefix": "sk_live_mer_7d21",
  "scopes": [
    "string"
  ],
  "allowed_ips": [
    "203.0.113.10"
  ],
  "is_active": true,
  "expires_at": "2026-01-15T12:30:00.000Z",
  "last_used_at": "2026-01-15T12:30:00.000Z",
  "created_at": "2026-01-15T12:30:00.000Z",
  "key_hash": "sk_live_mer_7d21"
}

Errors

Errors use the standard envelope. The most common cases here:

HTTPMeaning
400Invalid parameters or a state that does not allow this operation.
401Missing, expired, or invalid Dashboard session token.
403Authenticated, but the signed-in user lacks access to this entity.
404The record does not exist or is not visible to this entity.

On this page

The API key objectEndpointsGET /api/v1/org/api-keysPOST /api/v1/org/api-keysGET /api/v1/org/api-keys/scopesGET /api/v1/org/api-keys/:idPATCH /api/v1/org/api-keys/:idPOST /api/v1/org/api-keys/:id/revokeErrorsRelated