When a Seller API key has a non-empty allowed_ips list, only requests from those public IPv4 or
IPv6 addresses (or CIDR ranges) are accepted. Requests from any other address are refused with
403 IP_NOT_ALLOWED.
The rule#
This is the one statement of the rule; every other guide links here.
| Key | What it needs | What happens without it |
|---|---|---|
| Production | At least one egress IP, or a trusted workload binding. The console will not save a production key without one | While GET /whoami → capabilities.requireProductionAllowlistEnabled is true, every request is refused with 403 ALLOWLIST_REQUIRED. While it is false, requests from any address are accepted and GET /whoami carries the warning PRODUCTION_ALLOWLIST_MISSING |
| Sandbox | Nothing, and no list: neither the console nor the API sets one on a sandbox key (the API answers 422 SANDBOX_ALLOWLIST_NOT_ALLOWED) | Requests from any address are accepted |
And for every key:
- A non-empty list is always enforced, on production and sandbox keys alike.
- A trusted workload binding replaces the IP check. A bound key is checked against its workload token instead, and counts as pinned for the production requirement.
- The API applies the console's rules, on every contract date. PATCH /api-keys/{id}/allowed-ips
takes up to 50 entries, and the new list may not be wider than the calling key's own. An empty
list on a production key answers
422PRODUCTION_ALLOWLIST_REQUIREDunless the key is bound to a trusted workload; on a sandbox key only an empty list is accepted. A refused update leaves the list as it was. SeePATCH /api-keys/{id}/allowed-ips. - Changes take effect within about 60 seconds. Add the new address before you remove the old one.
GET /whoami → data.key.allowedIps shows the list the key carries now.
Why this matters#
A leaked API key is the single highest-impact failure mode for a digital distribution platform: an attacker who steals the key can pull inventory keys, issue refunds, and disable webhooks until the key is revoked.
Pinning each key to a small, customer-declared egress fingerprint changes the attack model from "steal the key, exfiltrate from anywhere" to "steal the key AND get on-network with one of N declared IPs".
What you can declare#
Up to 50 entries on the key's allowed_ips field. Each entry is either:
| Shape | Example | Notes |
|---|---|---|
| IPv4 address | 203.0.113.5 | Strict dotted-quad |
| IPv4 CIDR | 203.0.113.0/24 | Prefix 1–32. /0 is rejected. |
| IPv6 address | 2001:db8::1 | Lower-cased; ::ffff: v4-mapping ok |
| IPv6 CIDR | 2001:db8::/48 | Prefix 1–128. /0 is rejected. |
The following are rejected when configuring an allowlist:
- RFC1918 private (
10/8,172.16/12,192.168/16) - Loopback (
127/8,::1) - Link-local (
169.254/16,fe80::/10) - CGNAT (
100.64/10) - IPv6 ULA (
fc00::/7) - Multicast / documentation / benchmark (
224/4,192.0.2/24,198.51.100/24,203.0.113/24) - Anything that doesn't normalise to a valid literal
Error contract#
All denials return a 403 with a structured JSON body following the standard
flat ApiErrorResponse envelope (top-level code, not nested under error):
{
"code": "IP_NOT_ALLOWED",
"message": "Client IP 198.51.100.42 is not in this key's allowed_ips list. Update the key's allowed IPs in the Avrix dashboard (Settings → Integrations → API Keys) and retry.",
"details": {
"clientIp": "198.51.100.42",
"allowedIpsCount": 3,
"docsUrl": "https://docs.avrix.io/seller-api/ip-allowlist"
},
"requestId": "req_...",
"doc_url": "https://docs.avrix.io/seller-api/ip-allowlist"
}
code | When |
|---|---|
| IP_NOT_RESOLVABLE | Key has a non-empty allowlist but the request IP could not be determined from trusted proxy headers |
| IP_NOT_ALLOWED | Key has a non-empty allowlist and the client IP did not match any entry |
| ALLOWLIST_REQUIRED | Production key with an empty list and no trusted workload, while the requirement is on (the rule) |
We never echo the allowlist itself in the error body. We only confirm or deny — and on deny we echo the client's IP back so you can update the key.
Cache semantics#
Successful key authorisations may be cached briefly (~60s). The IP check is re-evaluated on every request, including cache hits. This means:
- Adding or removing an IP takes effect within about 60 seconds.
- A request from a new IP is denied immediately even if a previous request from a different IP just primed the cache.
Endpoints#
Key-management endpoints authenticate with an ordinary Seller API key that
holds the seller:keys:write scope — there is no separate admin
credential. A key minted over the API can never exceed the creating key's
ceiling: scopes are intersected with the parent's, expiry is inherited, and
allowed_ips must be a non-empty subset of the parent's list whenever the
parent is itself IP-restricted. These routes were first published under /keys
(POST /keys, PATCH /keys/{id}/allowed-ips); those paths still work.
POST /api/seller/v1/api-keys#
Create a new key. The request accepts no allowed_ips or up to 50 entries, but a production key
needs a list or a trusted workload before it can be used (the rule). Pass
includeFinanceScope: true only when the creating key already holds seller:finance:read.
curl -X POST https://api.avrix.io/api/seller/v1/api-keys \
-H "Authorization: Bearer ${AVRIX_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"name": "prod-fulfillment",
"allowed_ips": ["203.0.113.5", "203.0.113.0/24"]
}'
The 201 response is the only time the secret is returned:
{
"data": {
"id": "9f3c…",
"name": "prod-fulfillment",
"key": "avrix_sk_…",
"livemode": true
}
}
PATCH /api/seller/v1/api-keys/{id}/allowed-ips#
Replace the IP allowlist on an existing key without rotating the secret. Useful when your servers move egress IPs.
curl -X PATCH https://api.avrix.io/api/seller/v1/api-keys/${KEY_ID}/allowed-ips \
-H "Authorization: Bearer ${AVRIX_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"allowed_ips": ["203.0.113.5", "2001:db8::/48"]}'
Returns 204 No Content on success. The body replaces the whole list. [] removes the restriction;
see the rule before you send it for a production key.
The API applies the console's rules for which list a key may carry, on every contract date:
- A production key keeps at least one address. An empty
allowed_ipsanswers422 VALIDATION_FAILEDwithdetails.issues[0].codePRODUCTION_ALLOWLIST_REQUIRED, unless the key is bound to a trusted workload, which replaces the IP check. - A sandbox key takes no list: sandbox keys accept requests from any address. A non-empty list
answers
422 VALIDATION_FAILEDwithdetails.issues[0].codeSANDBOX_ALLOWLIST_NOT_ALLOWED. Clearing a sandbox key's list with[]is accepted.
A refused update leaves the key's list as it was.
When the calling key is itself IP-restricted, the new list must be a non-empty subset of its own
allowlist, also when it updates itself; anything wider answers 403 FORBIDDEN. Add a new egress
address in the console (Settings → Integrations → API Keys), or with a key that is not
IP-restricted.
GET /api/seller/v1/whoami-ip#
Public, unauthenticated. Echoes the request's normalised client IP. Used by:
- The dashboard's "Detect my IP" button (browser-side onboarding).
- Customer-side
curlfrom their integration host to confirm their egress IP before they put it in the allowlist.
curl https://api.avrix.io/api/seller/v1/whoami-ip
# → { "data": { "clientIp": "203.0.113.5" }, "meta": { "requestId": "req_..." } }
The endpoint never echoes any other request signal and never auths — the IP is already implicit in every request and is not itself a secret.
Trusted workload instead of IPs#
Serverless and container platforms usually have no fixed egress address: each invocation can leave from a different IP, so no allowlist can describe them. For those, a production key can be bound to a trusted workload instead. The platform signs a short-lived OIDC token for every invocation that names your account, project and environment; Avrix accepts the key only when the request carries such a token and it matches the binding exactly.
| Binding field | Example (team issuer mode) |
|---|---|
| Issuer | https://oidc.<platform>/<team> |
| Audience | the platform's default audience for your team |
| Subject | owner:<team>:project:<project>:environment:production |
Set the binding under Settings → Integrations → API Keys → Trusted workload, then send the token your platform gives the running function on every request:
Authorization: Bearer avrix_sk_live_…
X-Avrix-Workload-Token: <the invocation's OIDC token>
How it is checked:
- The token's signature must verify against the issuer's published signing keys (fetched once and cached; a rotated key is picked up automatically).
iss,audandsubmust equal the binding;expmust be in the future (60 seconds of clock skew allowed). OnlyRS256andES256tokens are accepted.- The check runs on every request, cache hit or not. For a bound key the IP allowlist is not consulted, and a key with a binding counts as pinned for the production allowlist requirement.
- Any failure returns
403 WORKLOAD_IDENTITY_INVALIDwithdetails.reason(missing,expired,claim_mismatch,bad_signature,untrusted_issuer,jwks_unavailableormalformed).
Only issuers on Avrix's supported list can be bound; the console offers them as presets. A stolen API key alone is useless against a bound key: the attacker would also need a fresh token signed for your project, which only your running deployment receives.
Header precedence (how we determine your IP)#
Client IP is taken from trusted proxy headers, in order:
- The edge platform's own forwarded-for header, when present.
x-real-ip— set by upstream proxies in custom deployments.x-forwarded-for— first (leftmost) hop.
If none of these resolve to a normalised literal we return IP_NOT_RESOLVABLE.
Configure your reverse proxy to forward x-forwarded-for if you terminate TLS
yourself.
Where to change it#
- Console: Settings → Integrations → API Keys. Production keys only; the console requires at least one entry or a trusted workload.
- API: PATCH /api-keys/{id}/allowed-ips with a key holding
seller:keys:write, without rotating the secret.
See also#
- Scope matrix — scopes required before keys can call the API
- Sandbox — test IP allowlist and auth triage without production traffic
- Error playbook —
IP_NOT_ALLOWEDand recovery steps