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

# API V3 IP Allowlist

> Restrict API V3 requests to trusted server IP addresses while keeping client IP resolution automatic with or without Cloudflare.

You can restrict API V3 access so that a merchant's API key is accepted only when the request comes from an approved server IP. This is useful when you want to ensure OTP requests are sent from your own backend infrastructure.

IP allowlisting is configured per merchant and uses exact public IPv4 or IPv6 addresses. It is independent of the global and per-destination [rate limits](/reference/rate-limits).

## Automatic IP resolution

OTP.ID resolves the request IP automatically using the first valid value in this order when the transport peer is a local/private reverse proxy or a Cloudflare edge:

1. `CF-Connecting-IP` — the original visitor IP supplied by Cloudflare
2. `X-Real-IP` — commonly set by a reverse proxy
3. The first address in `X-Forwarded-For` — the left-most client address
4. The direct connection address

This means no application setting needs to change when Cloudflare is bypassed. With Cloudflare enabled, `CF-Connecting-IP` is used. If the Cloudflare proxy is turned off and that header is absent, OTP.ID falls back automatically to the other headers or the direct peer address. If a request reaches the origin directly from a public peer, forwarding headers are ignored and the actual peer address is used instead.

<Warning>
  Your reverse proxy or firewall must overwrite incoming client-controlled forwarding headers and must protect the OTP.ID origin from direct public access. Otherwise, a caller could spoof a trusted header. See Cloudflare's guidance on [HTTP headers](https://developers.cloudflare.com/fundamentals/reference/http-headers/) and [protecting your origin](https://developers.cloudflare.com/fundamentals/security/protect-your-origin-server/).
</Warning>

## Whitelist format

Provide a comma-separated list of exact public IP addresses:

```text theme={null}
203.0.113.10, 198.51.100.7, 2001:db8::7
```

Rules:

* Whitespace around each comma-separated value is ignored.
* IPv4 and IPv6 are supported.
* CIDR notation such as `203.0.113.0/24` is not accepted.
* An empty whitelist allows every valid resolved IP.
* A malformed whitelist is rejected safely; it does not silently broaden access.

## Rejected request

When the resolved IP is not listed, the API returns HTTP `403`:

```json theme={null}
{
  "success": false,
  "data": null,
  "error": {
    "code": "IP_NOT_ALLOWED",
    "message": "IP request tidak diizinkan"
  }
}
```

The resolved client IP is recorded in OTP.ID's internal request logs for API V3 auditability. It is not returned as a field in the normal API response.