API key management

Create child keys, rotate secrets, update IP allowlists, and revoke keys over the API without signing into the console.

TopicsOperate

Programmatic lifecycle for Seller API keys: list, create child keys, rotate secrets, update IP allowlists, and revoke. Console creation remains the primary path for human operators; these routes support automation and least-privilege child keys.

Who needs this#

Platform teams that mint per-service keys from a parent key, rotate secrets without Console clicks, or update allowlists when egress IPs change.

TL;DR#

  • Listing keys (GET /api-keys) needs seller:keys:read or seller:keys:write; every other route needs seller:keys:write on the calling key.
  • POST /api-keys mints a child key with exactly the scopes you send, each held by the parent, or, when you send none, the server default set intersected with the parent’s scopes — children never exceed the parent ceiling.
  • Child keys inherit the parent’s environment, expire at the expiresAt you send or else with the parent, and cannot widen an IP allowlist.
  • GET /api-keys returns each key’s scopes, environment, allowlist, expiry and last use, for audits.
  • A key manages itself, or another key that does not exceed it — see Which keys a key can manage.
  • Secrets appear once on create/rotate. List responses are masked.
  • Fulfilment routes POST /keys/pull, POST /keys/export, and POST /keys/return are separate — see Fulfilment and keys.

Endpoints#

MethodPathPurpose
GET/api/seller/v1/api-keysList keys (masked) for the key’s owning company, in the calling key’s environment, with each key’s scopes, environment, allowedIps, expiresAt, lastUsedAt and status. seller:keys:read is enough
POST/api/seller/v1/api-keysCreate a child key; returns plaintext secret once
POST/api/seller/v1/api-keys/{id}/rotateRotate secret in place; returns new secret once
PATCH/api/seller/v1/api-keys/{id}/allowed-ipsReplace IP allowlist without rotating the secret
DELETE/api/seller/v1/api-keys/{id}Soft-revoke a key (stops auth; record retained for audit)

/keys paths act on game keys everywhere else in the API, so API keys are managed under /api-keys. The same operations under /api/seller/v1/keys (GET and POST /keys, /keys/{id}, /keys/{id}/rotate, /keys/{id}/allowed-ips) are their older paths: they run the same handlers, answer the same way, and keep working. See Naming conventions.

Sandbox keys list and mutate only your company’s keys — never other integrators on the shared sandbox catalog.

Which keys a key can manage#

Rotate, allowed-IPs and revoke follow the same ceiling as creation. The calling key can act on:

  • Itself.
  • Another key of your company that does not exceed it: same environment (sandbox or production), every scope of the target also held by the calling key, and an IP allowlist no wider than the calling key’s. When the calling key is IP-restricted, a new allowlist set through PATCH /api-keys/{id}/allowed-ips must be a non-empty subset of the calling key’s. This holds for the calling key’s own allowlist too: an IP-restricted key can narrow its allowlist, but adding an address or removing the restriction is done in the console or with a key that is not IP-restricted.

Everything else is refused:

TargetResponse
Key in the other environment (a sandbox key acting on a production key, or the reverse)404 NOT_FOUND — it is not listed either
Key with a scope the calling key lacks, or a wider IP allowlist403 FORBIDDEN
Key created by an MCP connector403 FORBIDDEN — disconnect the connector to revoke it

To manage a key that exceeds every API key you hold, use the console.

Create a child key#

POST /api/seller/v1/api-keys Authorization: Bearer <parent-key> Content-Type: application/json

Typical body:

JSON
{
  "name": "checkout-worker",
  "allowed_ips": ["203.0.113.10"],
  "scopes": ["seller:products:read", "seller:orders:preview", "seller:orders:write"],
  "expiresAt": "2027-03-31T00:00:00Z",
  "includeFinanceScope": false
}
FieldMeaning
nameRequired label (appears in audit logs)
allowed_ipsOptional. When the parent is IP-restricted, omit to inherit, or pass a non-empty subset. Empty array is rejected if the parent is restricted.
scopesOptional. The child’s scopes, exactly. Each must be held by the parent; one it lacks is refused with 403 INSUFFICIENT_SCOPE naming it in details.missingScopes, and no key is created. An unknown scope name is 422. Omit for the default set.
expiresAtOptional. When the child stops working (ISO 8601 with an offset): at least a minute ahead (422 otherwise) and no later than the parent’s expiry (403 otherwise). Omit to inherit the parent’s expiry.
includeFinanceScopeOptional. Adds finance read only if the parent already holds seller:finance:read. With scopes, adds it to that list.

The response repeats the child’s scopes and expiresAt.

Ceiling rules#

  • Scopes. Exactly scopes when sent, each of which the parent must hold; otherwise the server default set ∩ parent scopes. A scope the parent lacks, or an empty intersection → 403 INSUFFICIENT_SCOPE, on every contract date. A child never receives a scope the parent lacks.
  • Default set includes catalog, preview, pull, refunds, promotions, webhooks, and seller:keys:write (so a parent that holds seller:keys:write can mint children that also manage keys). seller:finance:read is opt-in via includeFinanceScope and still clamped to the parent. With scopes you choose any subset of the parent’s scopes instead. A key wider than every key you hold is created in the console.
  • Environment. Inherited from the parent (sandbox mints sandbox; production mints production).
  • Expiry. expiresAt when sent, otherwise inherited; children never outlive the parent. api_key.expiring is sent 14 days ahead (for keys meant to live longer than that) and api_key.expired when it passes.
  • IP allowlist. Cannot widen the parent’s restriction.

Store data.key immediately. Subsequent GETs never return the plaintext secret. POST /api-keys accepts an optional Idempotency-Key: a retry with the same key and body creates no second key, and its replayed answer carries secretRedacted: true instead of key.

Rotate#

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

Returns a new secret once. Send { "overlapSeconds": 3600 } (60 to 86400) to keep the replaced secret working until previousSecretExpiresAt, so you can roll the new one out without downtime; without a body the replaced secret stops at once. Send an Idempotency-Key and reuse it on retries: a retry does not rotate again (the replay carries secretRedacted: true, since the secret is never stored). Overlapping keys (create second key → cut over → revoke old) remain an option when many workers hold the secret — see Security and Authentication.

Update allowed IPs#

PATCH /api/seller/v1/api-keys/{id}/allowed-ips

Full replacement of the allowlist without rotating the secret. Use when NAT / region egress changes. Up to 50 entries, none wider than the calling key's own list. An empty array is accepted and removes the restriction, which a production key without a trusted workload cannot run on (the rule). The older path PATCH /keys/{id}/allowed-ips runs the same call. Details: IP allowlist.

Revoke#

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

Soft-revokes the key: authentication fails immediately, but the row is retained for audit (not hard-deleted). GET /api/seller/v1/api-keys keeps listing it with status: "revoked" and its revokedAt; active keys have status: "active" and revokedAt: null. Expect a short propagation window before all edges deny the token. Archiving (hiding from the default console list while keeping the record) is a console-only action.

What links here

Published guides that link to this page.

Search docs

Search documentation…