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

# Restrict API access with IP whitelisting

> Lock your Dubu Pay API credentials to specific IP addresses. Any request from an unlisted IP is rejected, even with a valid API key.

IP whitelisting lets you restrict which IP addresses can make API calls using your credentials. When you add an IP to the whitelist, Dubu Pay rejects any request that arrives from an address not on the list, even if it carries a valid API key. This significantly reduces the risk of credential misuse if your keys are ever exposed.

<Warning>
  Once you add any IP to your whitelist, **all** API requests must originate from a whitelisted address. Requests from any other IP — including your current one — will be rejected immediately. Make sure you add every IP you intend to use before enabling the whitelist.
</Warning>

## Add an IP address

Call `POST /ip-whitelist` with the IP address you want to allow. You can optionally include a `label` to help you identify the entry later (for example, `"production-server"` or `"office-nat"`).

Both IPv4 and IPv6 addresses are accepted.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.dubupay.com/api/v1/ip-whitelist \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "ip_address": "203.0.113.42",
      "label": "production-server"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.dubupay.com/api/v1/ip-whitelist', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      ip_address: '203.0.113.42',
      label: 'production-server',
    }),
  });

  const { data } = await response.json();
  console.log(data);
  ```
</CodeGroup>

A successful response returns the new whitelist entry:

```json theme={null}
{
  "success": true,
  "data": {
    "id": "wl_01HXK...",
    "ip_address": "203.0.113.42",
    "label": "production-server",
    "created_at": "2026-05-21T10:00:00.000Z"
  }
}
```

## List whitelisted IPs

Retrieve all IP addresses currently on your whitelist with `GET /ip-whitelist`.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.dubupay.com/api/v1/ip-whitelist \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.dubupay.com/api/v1/ip-whitelist', {
    headers: { 'Authorization': 'Bearer YOUR_ACCESS_TOKEN' },
  });

  const { data } = await response.json();
  console.log(data); // array of whitelist entries
  ```
</CodeGroup>

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "wl_01HXK...",
      "ip_address": "203.0.113.42",
      "label": "production-server",
      "created_at": "2026-05-21T10:00:00.000Z"
    },
    {
      "id": "wl_02HXK...",
      "ip_address": "203.0.113.99",
      "label": "backup-server",
      "created_at": "2026-05-21T10:05:00.000Z"
    }
  ]
}
```

## Remove a single IP

To remove one entry, pass its `id` to `DELETE /ip-whitelist/:id`. The `id` is the UUID returned when you added the entry.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE https://api.dubupay.com/api/v1/ip-whitelist/wl_01HXK... \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```

  ```javascript Node.js theme={null}
  const entryId = 'wl_01HXK...';

  const response = await fetch(`https://api.dubupay.com/api/v1/ip-whitelist/${entryId}`, {
    method: 'DELETE',
    headers: { 'Authorization': 'Bearer YOUR_ACCESS_TOKEN' },
  });

  const result = await response.json();
  console.log(result.message); // "IP removed from whitelist"
  ```
</CodeGroup>

## Clear all whitelisted IPs

To remove every entry at once, call `DELETE /ip-whitelist` without an ID. This disables IP restrictions entirely — requests from any IP will be accepted again until you add new entries.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE https://api.dubupay.com/api/v1/ip-whitelist \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.dubupay.com/api/v1/ip-whitelist', {
    method: 'DELETE',
    headers: { 'Authorization': 'Bearer YOUR_ACCESS_TOKEN' },
  });

  const result = await response.json();
  console.log(result.message); // "IP whitelist cleared"
  ```
</CodeGroup>

<Warning>
  Clearing the whitelist immediately removes all IP restrictions. Any client with a valid API key can then make requests from any IP address. Only do this intentionally and re-add your IPs as soon as possible.
</Warning>

## Best practices

<Tip>
  Use static IP addresses for your servers. Dynamic or residential IPs change frequently and will lock you out when they rotate.
</Tip>

* **Whitelist multiple IPs for redundancy.** If your primary server goes down and you fail over to another, that server's IP must already be on the whitelist or your API calls will fail.
* **Label every entry.** A clear label like `"eu-west-prod"` or `"ci-runner"` makes it easy to identify and remove specific entries later without guessing.
* **Audit the list regularly.** Remove IPs that belong to decommissioned servers or infrastructure you no longer use to keep your attack surface small.
* **Test from a whitelisted IP before going live.** Add your IP and verify a simple API call succeeds before routing production traffic through the whitelist.