Keys, scopes and limits
A key is a bearer token: Authorization: Bearer fp_live_…. It belongs to your account, carries a fixed set of scopes, and can be restricted to a list of addresses and given an expiry when it is minted. Up to twenty keys may be live at once, so a farm can give each deliverer, each machine and each tool its own and revoke one without touching the rest.
Scopes
| Scope | Lets a key |
|---|---|
catalog:read | Read games, lanes, realms and packages. Every key has it. |
listings:read | Read your listings, your boost offers and your code vault counts. |
listings:write | Create and change listings, land syncs, set tiers, stock codes, publish boost curves. |
orders:read | Read the order feed, one order, its timeline. |
orders:write | Accept, deliver, decline, add account credentials. |
chat:read | Read the thread with the buyer. |
chat:write | Post in it. |
account:read | Read your profile, presence and balance. |
account:write | Holiday mode, presence, the sandbox reset. |
webhooks:manage | Endpoints, secrets, the delivery log, replays. |
The console offers three presets: stock sync (catalog, listings), fulfilment (orders and chat) and full. A key without a route's scope gets a 403 whose body names the scope it lacks.
Rate limits
Budgets are per key, per minute, and slide rather than reset on the hour. Four buckets: reads, writes, bulk (syncs and code uploads) and chat. A new seller gets the base budget; standard and trusted sellers get two and three times it, so the tools that have earned trust are never the ones waiting. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset; a 429 carries Retry-After in seconds. Honour it: retrying inside the window only spends more of the next one.
Idempotency
Any write may carry an Idempotency-Key header, any string up to 200 characters that you will not reuse for a different request. A retry with the same key gets the first answer back with Idempotent-Replayed: true, for a day. The same key on a different body or path is refused with idempotency_key_reused, which is the API telling you a bug in your retry loop before it costs anything.
Signed requests, if you want them
A key can be switched to signed requests from Integrations. From then on each request carries Freeport-Timestamp and Freeport-Signature: v1=<hex>, an HMAC-SHA256 with the key's signing secret over the timestamp, method, request target and a hash of the body; a signature is accepted once inside a five-minute window. A stolen key is then useless without the secret, which never travels. See Signing.
What a key survives
A password change: yes. Keys are their own credential and a seller rotating a password should not lose every integration at once. A suspension: reads keep working and writes that start something new are refused, the same rule as the console. Revoking API access from the ops side ends every key at once; revoking one key ends that key within seconds everywhere.