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#
- All routes require
seller:keys:writeon the calling key. POST /keysmints a child key whose scopes are the server default set intersected with the parent’s scopes — children never exceed the parent ceiling.- Child keys inherit the parent’s environment and expiry, and cannot widen an IP allowlist.
- 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/keys | List keys (masked) for the key’s owning company |
POST | /api/seller/v1/keys | Create a child key; returns plaintext secret once |
POST | /api/seller/v1/keys/{id}/rotate | Rotate secret in place; returns new secret once |
PATCH | /api/seller/v1/keys/{id}/allowed-ips | Replace IP allowlist without rotating the secret |
DELETE | /api/seller/v1/keys/{id} | Soft-revoke a key (stops auth; record retained for audit) |
Sandbox keys list and mutate only your company’s keys — never other integrators on the shared sandbox catalog.
Create a child key#
POST /api/seller/v1/keys
Authorization: Bearer <parent-key>
Content-Type: application/json
Typical body:
{
"name": "checkout-worker",
"allowed_ips": ["203.0.113.10"],
"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. |
includeFinanceScope | Optional. Adds finance read only if the parent already holds seller:finance:read. |
Ceiling rules#
- Scopes. Server default set ∩ parent scopes. If the intersection is empty → 403 INSUFFICIENT_SCOPE. 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. Console creation can select any scope combination; API create always starts from that default set. - Environment. Inherited from the parent (sandbox mints sandbox; production mints production).
- Expiry. Inherited; children never outlive the parent.
- IP allowlist. Cannot widen the parent’s restriction.
Store data.key immediately. Subsequent GETs never return the plaintext secret.
Rotate#
POST /api/seller/v1/keys/{id}/rotate
Returns a new secret once. Prefer overlapping keys (create second key → cut over → revoke old) when you need zero downtime across many workers — see Security.
Update allowed IPs#
PATCH /api/seller/v1/keys/{id}/allowed-ips
Full replacement of the allowlist without rotating the secret. Use when NAT / region egress changes. Details: IP allowlist.
Revoke#
DELETE /api/seller/v1/keys/{id}
Soft-revokes the key: authentication fails immediately, but the row is retained for audit (not hard-deleted). 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.