API Keys

Create, list, rotate, and revoke tenant API keys. All of these endpoints require a key with the admin scope. This is also the only way to mint narrow-scoped keys — the Settings → API Keys screen creates coarse single-scope keys, while this API accepts any combination from the full scope vocabulary. See Authentication for how the scopes expand.

Accepted scopes values:

• read — coarse: read everything the coarse v1 surface exposes.

• commerce — coarse: read plus the cart/checkout commerce surface.

• admin — coarse: everything, including every narrow scope below.

• journeys:read — read journeys.

• journeys:write — create and edit journeys (implies journeys:read).

• journeys:publish — publish, deactivate, or delete live journeys (implies journeys:read).

• journeys:delete — delete draft or archived journeys (implies journeys:read).

• pages:read — read pages.

• pages:write — create and edit pages (implies pages:read).

• pages:publish — publish or unpublish pages (implies pages:read).

• pages:delete — delete pages (implies pages:read).

• components:read — read components.

• components:write — create and edit components (implies components:read).

• components:delete — delete components (implies components:read).

Reserved (accepted on create, no endpoint requires them yet): productsets:read/write/delete, rules:read/write/delete, catalog:read (the one narrow read that coarse read/commerce keys expand to), and catalog:write-native.

Endpoints

GET /api/v1/api-keys

List API keys for the tenant (secrets are never returned in list responses)

get

/api-keys

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Scoped secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.

Query parameters

limitinteger · min: 1 · max: 100Optional

Max items to return (1–100, default 20)

Default: 20

offsetintegerOptional

Number of items to skip (default 0)

Default: 0

includeRevokedbooleanOptional

Include revoked keys in the response

Default: false

Responses

200

Paginated list of API key records (no secrets)

application/json

An API key record (secret is never returned except at create/rotate time)

idstring · uuidOptional

namestringOptional

keyPrefixstringOptional

First 10 characters of the key for identification

rateLimitTierstring · enumOptionalPossible values:

isActivebooleanOptional

revokedAtstring · date-time · nullableOptional

lastUsedAtstring · date-time · nullableOptional

expiresAtstring · date-time · nullableOptional

createdAtstring · date-timeOptional

get/api-keys

GET /api/v1/api-keys HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

200

Paginated list of API key records (no secrets)

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "keyPrefix": "text",
  "scopes": [
    "read"
  ],
  "rateLimitTier": "standard",
  "isActive": true,
  "revokedAt": "2026-01-01T00:00:00.000Z",
  "lastUsedAt": "2026-01-01T00:00:00.000Z",
  "expiresAt": "2026-01-01T00:00:00.000Z",
  "createdAt": "2026-01-01T00:00:00.000Z"
}

Notes, examples, or caveats for GET /api-keys go here.

POST /api/v1/api-keys

Create a new API key — the plaintext secret is returned only in this response

post

/api-keys

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Scoped secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.

Header parameters

Idempotency-KeystringOptional

Idempotency key to prevent duplicate key creation

Body

namestringRequired

rateLimitTierstring · enumOptionalDefault: standardPossible values:

expiresAtstring · date-timeOptional

Responses

201

API key created — includes one-time plaintext secret

application/json

Response from creating or rotating an API key — includes the one-time plaintext secret

requestIdstringOptional

400

Validation error

application/json

post/api-keys

POST /api/v1/api-keys HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 99

{
  "name": "text",
  "scopes": [
    "read"
  ],
  "rateLimitTier": "standard",
  "expiresAt": "2026-01-01T00:00:00.000Z"
}

{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text",
    "keyPrefix": "text",
    "scopes": [
      "read"
    ],
    "rateLimitTier": "standard",
    "isActive": true,
    "revokedAt": "2026-01-01T00:00:00.000Z",
    "lastUsedAt": "2026-01-01T00:00:00.000Z",
    "expiresAt": "2026-01-01T00:00:00.000Z",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "secret": "text"
  },
  "meta": {
    "secretNote": "text",
    "replacedKeyId": "text"
  },
  "requestId": "text"
}

scopes is an array drawn from the values listed in the overview above (defaults to ["read"]). One key may hold several narrow scopes — e.g. ["journeys:read", "journeys:write", "pages:read"]. Remember publish is never implied by write: grant it explicitly only to keys that should change what is live. Narrow-scoped keys appear on the Settings → API Keys screen but are edited through this API so their grants aren't collapsed by the screen's single-scope picker.

DELETE /api/v1/api-keys/{id}

Revoke an API key

delete

/api-keys/{id}

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Scoped secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.

Path parameters

idstringRequired

Responses

200

API key revoked

No content

404

Key not found

application/json

delete/api-keys/{id}

DELETE /api/v1/api-keys/{id} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Notes, examples, or caveats for DELETE /api-keys/{id} go here.

PATCH /api/v1/api-keys/{id}

Edit an API key's name and/or scopes in place

patch

/api-keys/{id}

Grants or removes scopes on an existing key without minting a new credential, e.g. adding handoffs:redeem to a key an app already uses. Audited with the old and new scopes. A revoked key cannot be edited.

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Scoped secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.

Path parameters

idstringRequired

Body

namestringOptional

scopesstring[]Optional

The key's complete new scope list

Responses

200

Updated key (no secret)

No content

400

Validation failed

application/json

404

API key not found

application/json

409

API key is revoked

application/json

patch/api-keys/{id}

PATCH /api/v1/api-keys/{id} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 33

{
  "name": "text",
  "scopes": [
    "text"
  ]
}

No content

Notes, examples, or caveats for PATCH /api-keys/{id} go here.

POST /api/v1/api-keys/{id}/rotate

Rotate an API key — revokes the old key and creates a new one with the same name and scopes. The new plaintext secret is returned only in this response.

post

/api-keys/{id}/rotate

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Scoped secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.

Path parameters

idstringRequired

Responses

201

New API key issued — includes one-time plaintext secret

application/json

Response from creating or rotating an API key — includes the one-time plaintext secret

requestIdstringOptional

404

Key not found

application/json

409

Key is already revoked

application/json

post/api-keys/{id}/rotate

POST /api/v1/api-keys/{id}/rotate HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text",
    "keyPrefix": "text",
    "scopes": [
      "read"
    ],
    "rateLimitTier": "standard",
    "isActive": true,
    "revokedAt": "2026-01-01T00:00:00.000Z",
    "lastUsedAt": "2026-01-01T00:00:00.000Z",
    "expiresAt": "2026-01-01T00:00:00.000Z",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "secret": "text"
  },
  "meta": {
    "secretNote": "text",
    "replacedKeyId": "text"
  },
  "requestId": "text"
}

Rotation preserves the key's full scope set — including narrow scopes — so it is always safe for narrow-scoped keys.