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

# IP allowlist

> Allow API calls only from your own network ranges, switch enforcement on safely, and troubleshoot ip-not-allowed errors.

The IP allowlist restricts which source addresses may call the API for your partner. It protects you if an API key leaks: a stolen key is useless outside your networks.

> [!WARNING]
>
> Use the API playground on these docs only with sandbox `vk_test_` keys. Playground requests are sent from Mintlify's servers, so they fail when your sandbox IP allowlist is enforced.

## How the allowlist works

* Your partner has up to **100** CIDR entries, each with a label.

* The setting `ipAllowlistEnforcement` decides what is checked:

  | Value | Effect |
  | - | - |
  | `off` (default) | Nothing is checked, even if entries exist |
  | `api-keys` | Every API-key request must come from an address inside an entry |
  | `api-keys-and-users` | API-key requests **and** dashboard users' requests must come from an address inside an entry |

* The address checked is your client's public source address, which is your **outbound NAT or proxy address**, not a private address inside your network. The API hosts are served through Cloudflare, and AllRide takes the address from the connection Cloudflare received from you (Cloudflare's `CF-Connecting-IP`), not from Cloudflare's own addresses. Headers such as `X-Forwarded-For`, `X-Client-IP` or `CF-Connecting-IP` that you send yourself are ignored or overwritten.

* A request from outside the allowlist is refused with `403` [`ip-not-allowed`](https://docs-consumer.voucher.allride.io/errors/catalog#ip-not-allowed). The response does not echo the address. The denial is recorded in your [audit log](https://docs-consumer.voucher.allride.io/workspace/audit-log.md) as `security.ip-denied` (at most once per key or member per minute).

* Changes take effect on every server within 60 seconds.

## Add your IP ranges

Add entries in [IP allowlist](https://consumer-developers.voucher.allride.io/go/ip-allowlist) in the developer dashboard, or with [`POST /partner/v1/ip-allowlist`](https://docs-consumer.voucher.allride.io/api-reference/partner-ip-allowlist-create) from a dashboard session. Changing the allowlist needs `manage-ip-allowlist` and a recent sign-in; it is not available to API keys, so a leaked key cannot widen its own access. Reading it ([`GET /partner/v1/ip-allowlist`](https://docs-consumer.voucher.allride.io/api-reference/partner-ip-allowlist-list)) needs `view-ip-allowlist` and works with API keys.

```json theme={null}
{
  "cidr": "203.0.113.0/24",
  "label": "Production NAT gateway"
}
```

Rules for `cidr`:

* canonical form with the host bits set to zero (`203.0.113.0/24`, not `203.0.113.7/24`); a single address is `/32` (IPv4) or `/128` (IPv6);
* IPv4 prefixes of `/8` or longer, IPv6 prefixes of `/32` or longer;
* no private, loopback or link-local ranges (such as the RFC 1918 private ranges or IPv6 link-local addresses) in production.

An invalid entry fails with `400` [`data-failed-validation`](https://docs-consumer.voucher.allride.io/errors/catalog#data-failed-validation) and the constraint [`invalid-cidr`](https://docs-consumer.voucher.allride.io/errors/catalog#invalid-cidr). Adding a CIDR that already exists answers `409` [`ip-allowlist-entry-exists`](https://docs-consumer.voucher.allride.io/errors/catalog#ip-allowlist-entry-exists); a 101st entry answers `422` [`ip-allowlist-limit-reached`](https://docs-consumer.voucher.allride.io/errors/catalog#ip-allowlist-limit-reached). To change a range, delete the entry and add a new one; only the label can be edited.

## Enable enforcement

1. Add **all** the ranges your systems call from (IPv4 and IPv6, every region and every fallback NAT) **before** you enable enforcement.
2. Set `ipAllowlistEnforcement` to `api-keys` in your partner's security settings in the dashboard. This needs `manage-settings` and is not available to API keys.
3. Watch your integration and the audit log for `security.ip-denied` for a while.
4. Optionally switch to `api-keys-and-users` to restrict dashboard access too.

Safety rules protect you from locking yourself out:

* Enforcement cannot be switched on while the allowlist is empty, and the last entry cannot be deleted while enforcement is on: both answer `409` [`ip-allowlist-required`](https://docs-consumer.voucher.allride.io/errors/catalog#ip-allowlist-required). Switch enforcement `off` first.
* With `api-keys-and-users`, a change that would exclude your own current address is refused with `422` [`ip-allowlist-would-lock-out`](https://docs-consumer.voucher.allride.io/errors/catalog#ip-allowlist-would-lock-out).

## IPv6

`api.voucher.allride.io` and `api.voucher-staging.allride.io` resolve to both IPv4 and IPv6 addresses. If your servers have IPv6 connectivity, they may connect over IPv6, and the address checked is then your IPv6 egress address. Either add your IPv6 egress range (for example `2001:db8:1200::/48`), or force your HTTP client to use IPv4. IPv4-mapped IPv6 addresses (`::ffff:203.0.113.7`) are matched against your IPv4 entries.

## Troubleshooting

| Symptom | Likely cause | Fix |
| - | - | - |
| `403 ip-not-allowed` after a deployment | The new environment uses a different NAT address | Add the new egress range |
| `403 ip-not-allowed` from some servers only | Some hosts connect over IPv6 | Add your IPv6 range or force IPv4 |
| Calls fail from your laptop but work from servers | Expected: your office address is not on the list | Use a host inside an allowed range |
| The docs playground fails | The playground calls from Mintlify's servers | Use the playground only with sandbox keys and enforcement off, or use `curl` |
| `409 ip-allowlist-required` | Enforcement is on and you tried to delete the last entry, or switched it on with no entries | Add entries first, or switch enforcement off |

To find the address AllRide sees, call any endpoint from the host in question with enforcement off, then check `lastUsedIp` of the key in the developer dashboard.

## Related

* [Network and IP addresses](https://docs-consumer.voucher.allride.io/guides/network.md)
* [Authentication](https://docs-consumer.voucher.allride.io/guides/authentication.md)


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