> ## 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 Allowlisting

> Restrict API access to a specific set of trusted IP addresses

IP allowlisting lets you lock down your Yativo API integration so that only requests originating from your approved server IPs are accepted. Any API call from an unregistered IP returns `403 Forbidden`.

This is a strongly recommended security control for production integrations — particularly for payout and wallet operations.

<Note>
  IP allowlisting is enforced at the API level. Once you add any IP address, requests from all other IPs will be rejected. Only add IPs after you have confirmed your server's outbound IP address.
</Note>

***

## List Allowlisted IPs

```
GET https://api.yativo.com/api/v1/ip
```

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET 'https://api.yativo.com/api/v1/ip' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "status": "success",
    "status_code": 200,
    "message": "Request successful",
    "data": [
      {
        "id": "ip-a1b2c3",
        "ip_address": "203.0.113.10",
        "label": "Production server",
        "created_at": "2026-04-01T10:00:00.000000Z"
      }
    ]
  }
  ```
</ResponseExample>

***

## Add IP Address

```
POST https://api.yativo.com/api/v1/ip
```

<Note>
  Requires `Idempotency-Key` header.
</Note>

<ParamField body="ip_address" type="string" required>
  The IPv4 address to allowlist (e.g. `"203.0.113.10"`). CIDR ranges are not supported — add individual IPs.
</ParamField>

<ParamField body="label" type="string">
  A descriptive label for this IP (e.g. `"Production server"`, `"CI/CD runner"`).
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST 'https://api.yativo.com/api/v1/ip' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
    -H 'Content-Type: application/json' \
    -H 'Idempotency-Key: add-ip-001' \
    -d '{
      "ip_address": "203.0.113.10",
      "label": "Production server"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.yativo.com/api/v1/ip', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': `add-ip-${Date.now()}`,
    },
    body: JSON.stringify({
      ip_address: '203.0.113.10',
      label: 'Production server',
    }),
  });
  const data = await response.json();
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "status": "success",
    "status_code": 200,
    "message": "IP addresses whitelisted and added to firewall."
  }
  ```
</ResponseExample>

***

## Update IP Address

```
PUT https://api.yativo.com/api/v1/ip/{id}
```

<ParamField path="id" type="string" required>
  The IP record ID to update.
</ParamField>

<ParamField body="ip_address" type="string" required>
  The new IP address to replace the existing one.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X PUT 'https://api.yativo.com/api/v1/ip/ip-a1b2c3' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
    -H 'Content-Type: application/json' \
    -H 'Idempotency-Key: update-ip-001' \
    -d '{
      "ip_address": "203.0.113.20"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "status": "success",
    "status_code": 200,
    "message": "IP addresses updated and added to firewall."
  }
  ```
</ResponseExample>

***

## Remove IP Address

```
DELETE https://api.yativo.com/api/v1/ip/{id}
```

<Warning>
  Removing all IPs effectively disables allowlisting — all IPs will be permitted again. If you want to maintain the restriction, always keep at least one IP in the list.
</Warning>

<ParamField path="id" type="string" required>
  The IP record ID to remove.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X DELETE 'https://api.yativo.com/api/v1/ip/ip-a1b2c3' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "status": "success",
    "status_code": 200,
    "message": "IP address removed from whitelist and firewall."
  }
  ```

  ```json Not found theme={null}
  {
    "status": "error",
    "status_code": 400,
    "message": "IP address not found"
  }
  ```
</ResponseExample>