IP allowlist

Optional egress IP restrictions for API keys.

TopicsOperate

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.

KeyWhat it needsWhat happens without it
ProductionAt least one egress IP, or a trusted workload binding. The console will not save a production key without oneWhile 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
SandboxNothing, 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 422 PRODUCTION_ALLOWLIST_REQUIRED unless 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. See PATCH /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:

ShapeExampleNotes
IPv4 address203.0.113.5Strict dotted-quad
IPv4 CIDR203.0.113.0/24Prefix 1–32. /0 is rejected.
IPv6 address2001:db8::1Lower-cased; ::ffff: v4-mapping ok
IPv6 CIDR2001:db8::/48Prefix 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):

JSON
{
  "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"
}
codeWhen
IP_NOT_RESOLVABLEKey has a non-empty allowlist but the request IP could not be determined from trusted proxy headers
IP_NOT_ALLOWEDKey has a non-empty allowlist and the client IP did not match any entry
ALLOWLIST_REQUIREDProduction 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.

Bash
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:

JSON
{
  "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.

Bash
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_ips answers 422 VALIDATION_FAILED with details.issues[0].code PRODUCTION_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_FAILED with details.issues[0].code SANDBOX_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 curl from their integration host to confirm their egress IP before they put it in the allowlist.
Bash
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 fieldExample (team issuer mode)
Issuerhttps://oidc.<platform>/<team>
Audiencethe platform's default audience for your team
Subjectowner:<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:

HTTP
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, aud and sub must equal the binding; exp must be in the future (60 seconds of clock skew allowed). Only RS256 and ES256 tokens 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_INVALID with details.reason (missing, expired, claim_mismatch, bad_signature, untrusted_issuer, jwks_unavailable or malformed).

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:

  1. The edge platform's own forwarded-for header, when present.
  2. x-real-ip — set by upstream proxies in custom deployments.
  3. 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#

What links here

Published guides that link to this page.

Search docs

Search documentation…