> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yativo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# IP Whitelisting

> Limit each API key to the servers allowed to use it

Every API key has an **IP whitelist**: the public IP addresses of the servers allowed to use it. Requests made with the key must come from one of those IPs, or they're rejected with `403`.

<Warning>
  IP whitelists are enforced from **midnight on 14 October 2026**. Before then, run the [check](#check-your-ip) from every server that uses a key.
</Warning>

***

## Find your server's public IP

Whitelist the **public** IP your requests leave from. Private addresses such as `10.x.x.x` or `192.168.x.x` don't work.

Run this on the server that will call the API:

```bash theme={null}
curl https://checkip.amazonaws.com
```

| Setup | What to whitelist |
| - | - |
| Single server | Its static public IP |
| Kubernetes, serverless, autoscaling | The NAT gateway or egress IP |
| Several servers or regions | Each egress IP, or a CIDR range you control |
| Outbound proxy | The proxy's public IP |
| Dynamic IPs (home connections, some hosting platforms) | Not supported. Set up a static egress IP first |

***

## Whitelist rules

* Every key needs at least one entry, and can have up to 50.
* Each entry is a single IPv4 or IPv6 address (`203.0.113.10`, `2001:db8::1`) or a CIDR range (`198.51.100.0/28`).
* Ranges can't be broader than `/16` for IPv4 or `/32` for IPv6. `0.0.0.0/0` is rejected.
* IPs added under **Profile → Whitelist** apply to every API key on your account, on top of each key's own list.
* Setting `X-Forwarded-For` or similar headers yourself has no effect.

***

## Add or change IPs

**On a new key:** enter the IPs in **Allowed IPs** when you generate the key. See [API Keys](/yativo-fiat/api-keys#create-a-key).

**On an existing key:** go to **Developers → API Keys** and click **Edit IPs** on the key. The list you save replaces the current one, and the key and secret stay the same.

**For every key at once:** add the IP under **Profile → Whitelist**.

<Tip>
  When moving servers, add the new IP first, deploy, then remove the old one. This avoids downtime.
</Tip>

***

## Check your IP

Call [`GET /ip-whitelist/check`](/fiat-api-reference/ip/check) from the server that uses the key. It never blocks, so you can run it any time, including right after changing a whitelist.

```bash theme={null}
curl 'https://api.yativo.com/api/v1/ip-whitelist/check' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET'
```

```json theme={null}
{
  "status": "success",
  "status_code": 200,
  "message": "Request successful",
  "data": {
    "key_usage": {
      "authenticated_with_api_key": true,
      "key": "yativo_pk_9f1c2a...",
      "request_ip": "203.0.113.10",
      "allowed_server": true,
      "matched_entry": "203.0.113.10",
      "message": "This API key is being used from an allowed server (203.0.113.10 matches 203.0.113.10)."
    },
    "result": "pass",
    "summary": "203.0.113.10 passes the IP whitelist.",
    "tested_ip": "203.0.113.10",
    "tested_ip_source": "detected"
  }
}
```

| Field | Meaning |
| - | - |
| `key_usage.allowed_server` | `true` if the server that sent this request can use the key. |
| `key_usage.request_ip` | The IP Yativo sees for your request. Whitelist this if it isn't the IP you expected. |
| `key_usage.message` | The result in one sentence, including the error you'd get if the server isn't allowed. |
| `result` | `pass` or `fail` for `tested_ip`. |
| `network.warning` | Set when your request reached Yativo through a proxy, so `request_ip` may be the proxy's IP. Contact support if it isn't your server's public IP. |
| `api_key.key_allowed_ips` | The IPs listed on this key. |
| `api_key.account_whitelisted_ips` | IPs from **Profile → Whitelist** that also apply to this key. |
| `api_key.would_return` | The error a request from `tested_ip` would get, or `null` if allowed. |

The full response is in the [API reference](/fiat-api-reference/ip/check).

To check a server you haven't deployed yet, add `?ip=<address>`. `result` then describes that address, and `key_usage` still describes the server you called from.

***

## Errors

| HTTP | `data.error` | Fix |
| - | - | - |
| 403 | `This IP address is not allowed to use this API key.` | Check your server's public IP and add it to the key. |
| 403 | `This API key has no whitelisted IP addresses. ...` | Add at least one IP to the key. |
| 403 | `IP whitelists and API keys can only be managed from the Yativo dashboard.` | From 15 October 2026, make the change in the dashboard. |

***

## FAQ

<AccordionGroup>
  <Accordion title="Does the whitelist apply to dashboard sign-in?">
    No. It only applies to requests made with an API key. People can sign in to the dashboard from any network.
  </Accordion>

  <Accordion title="Can I allow any IP?">
    No. Every key needs a whitelist, and ranges broader than `/16` (IPv4) or `/32` (IPv6) are rejected.
  </Accordion>

  <Accordion title="My key worked and now returns 403.">
    Your server's public IP has probably changed. Run the check endpoint from that server and add the new `request_ip` to the key.
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.