Skip to main content

Client API Keys API

Manage overlapping API keys for server-to-server integrations without forcing an immediate cutover.

tip

Use this API when you want to create a replacement key, update downstream integrations gradually, and revoke the old key only after rollout is complete.

Authentication​

These endpoints require a B2B client admin token for the target client, or a GOFA super admin token.

GET /api/clients/[clientId]/api-keys​

Return the API keys configured for a client. The response includes metadata only; raw key values are not returned.

Response​

Sample Response
{
  "apiKeys": [
    {
      "keyId": "4c9f6b8d3c19e6a1",
      "label": "Production webhook",
      "maskedKey": "abc123...wxyz",
      "prefix": "abc123",
      "suffix": "wxyz",
      "status": "active",
      "isPrimary": true,
      "createdAt": "2026-03-24T09:15:00.000Z",
      "createdBy": "user_123",
      "expiresAt": null,
      "revokedAt": null,
      "lastUsedAt": "2026-03-24T12:32:18.000Z"
    }
  ],
  "legacyPrimaryKeyId": "4c9f6b8d3c19e6a1"
}

POST /api/clients/[clientId]/api-keys​

Create a new API key for the client.

Request Body​

Request Body
{
  "label": "Production webhook",
  "makePrimary": false
}
FieldTypeRequiredDescription
labelstringNoOptional operator-friendly label for the key
makePrimarybooleanNoIf true, promote the new key as the legacy-compatible primary key immediately

Response​

Success Response
{
  "success": true,
  "apiKey": {
    "keyId": "4c9f6b8d3c19e6a1",
    "label": "Production webhook",
    "maskedKey": "abc123...wxyz",
    "prefix": "abc123",
    "suffix": "wxyz",
    "status": "active",
    "isPrimary": false,
    "createdAt": "2026-03-24T09:15:00.000Z",
    "createdBy": "user_123",
    "expiresAt": null,
    "revokedAt": null,
    "lastUsedAt": null
  },
  "secret": "raw-secret-value",
  "clientSecret": "raw-secret-value"
}
warning

The raw secret is returned only in the create response. Persist it in your backend or secret manager before closing the page.

PATCH /api/clients/[clientId]/api-keys/[keyId]​

Update an existing API key.

Supported Actions​

Promote a key to primary​

Promote Request
{
  "action": "promote"
}

Promoting a key changes the backward-compatible primary key used by legacy single-secret flows, but does not revoke any other active keys.

Revoke a key​

Revoke Request
{
  "action": "revoke"
}

Revoking a key immediately disables it. If the revoked key is currently primary, the server automatically promotes another active key when available. The last active key cannot be revoked.

Response​

Success Response
{
  "success": true,
  "apiKeys": [
    {
      "keyId": "4c9f6b8d3c19e6a1",
      "label": "Production webhook",
      "maskedKey": "abc123...wxyz",
      "prefix": "abc123",
      "suffix": "wxyz",
      "status": "active",
      "isPrimary": true,
      "createdAt": "2026-03-24T09:15:00.000Z",
      "createdBy": "user_123",
      "expiresAt": null,
      "revokedAt": null,
      "lastUsedAt": "2026-03-24T12:32:18.000Z"
    }
  ],
  "legacyPrimaryKeyId": "4c9f6b8d3c19e6a1"
}

Backward Compatibility​

  • The platform still maintains a single legacy-compatible primary key under the hood for older flows.
  • Creating a new key does not disable existing active keys.
  • Use promotion when you are ready to move legacy traffic to a new key.
  • Revoke old keys only after downstream systems have switched successfully.