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) needsseller:keys:readorseller:keys:write; every other route needsseller:keys:writeon the calling key. POST /api-keysmints a child key with exactly thescopesyou 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
expiresAtyou send or else with the parent, and cannot widen an IP allowlist. GET /api-keysreturns 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#
| Method | Path | Purpose |
|---|---|---|
GET | /api/seller/v1/api-keys | List 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-keys | Create a child key; returns plaintext secret once |
POST | /api/seller/v1/api-keys/{id}/rotate | Rotate secret in place; returns new secret once |
PATCH | /api/seller/v1/api-keys/{id}/allowed-ips | Replace 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-ipsmust 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:
| Target | Response |
|---|---|
| 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 allowlist | 403 FORBIDDEN |
| Key created by an MCP connector | 403 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:
{
"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
}
| Field | Meaning |
|---|---|
name | Required label (appears in audit logs) |
allowed_ips | Optional. When the parent is IP-restricted, omit to inherit, or pass a non-empty subset. Empty array is rejected if the parent is restricted. |
scopes | Optional. 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. |
expiresAt | Optional. 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. |
includeFinanceScope | Optional. 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
scopeswhen 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 holdsseller:keys:writecan mint children that also manage keys).seller:finance:readis opt-in viaincludeFinanceScopeand still clamped to the parent. Withscopesyou 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.
expiresAtwhen sent, otherwise inherited; children never outlive the parent.api_key.expiringis sent 14 days ahead (for keys meant to live longer than that) andapi_key.expiredwhen 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.