> For the complete documentation index, see [llms.txt](https://docs.cortecs.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cortecs.ai/web-console/ip-whitelists.md).

# IP Whitelists

Restrict project API access to trusted IP addresses and networks

IP whitelists let you restrict project API access to specific IP addresses or networks. Use them to allow requests from your application servers, office network, or VPN while blocking requests from other sources, even when they use a valid API key.

Open [**Console > Project**](https://cortecs.ai/userArea/console?tab=project), select the project you want to configure, and find **IP Whitelist**.

{% hint style="info" %}
Only project administrators can view and manage the whitelist. The whitelist applies to the whole project, across all teams and API keys.
{% endhint %}

***

## How the whitelist works

The status next to **IP Whitelist** shows whether filtering is enabled:

| Status       | Behavior                                                                                                           |
| ------------ | ------------------------------------------------------------------------------------------------------------------ |
| **Disabled** | The whitelist is empty. Requests are allowed from any IP address, subject to the usual API key and project checks. |
| **Active**   | At least one entry is saved. Requests must come from a listed address or fall within a listed CIDR range.          |

Saving the first entry activates the whitelist. Removing the last entry disables it.

{% hint style="warning" %}
Before adding the first entry, identify the public outbound IP addresses used by your applications. Requests from unlisted addresses will be blocked once the whitelist is active. If your applications use both IPv4 and IPv6, add the required addresses or ranges for each.
{% endhint %}

***

## Add an IP address or range

1. Click **Add an IP address or range**.
2. Enter one IPv4 address, IPv6 address, or CIDR range.
3. Click **Save**.
4. Send a request from your application to confirm that it can still access the API.

![ipwhitelist\_add.png](https://2211217319-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYGsEKyV2Zq4Q8fEJQT40%2Fuploads%2Fgit-blob-d16712a3c327b3649080de38cac884a3840b4a91%2Fipwhitelist_add.png?alt=media)

Repeat these steps for each address or network that needs access.

### Supported formats

| Format          | Example          | What it allows                     |
| --------------- | ---------------- | ---------------------------------- |
| IPv4 address    | `203.0.113.10`   | One IPv4 address                   |
| IPv6 address    | `2001:db8::10`   | One IPv6 address                   |
| IPv4 CIDR range | `203.0.113.0/24` | All IPv4 addresses in that network |
| IPv6 CIDR range | `2001:db8::/64`  | All IPv6 addresses in that network |

These examples are for illustration. Replace them with your own addresses or networks.

CIDR ranges must start at the network address. For example, use `203.0.113.0/24` rather than `203.0.113.10/24`. Enter IP addresses directly; hostnames and URLs are not supported.

{% hint style="info" %}
Use the outbound IP address seen by the API. If requests pass through a VPN, proxy, or NAT gateway, this can be different from your device's local IP address. For applications with changing outbound addresses, use a stable outbound IP or an appropriate network range.
{% endhint %}

***

## When a range includes existing IP addresses

If you add a CIDR range that contains individual addresses already in the whitelist, you will be asked to confirm their replacement. The **Replace existing IP addresses?** dialog will list the affected entries.

* Choosing **Replace with CIDR** will remove those individual entries and save the range instead.
* Choosing **Keep existing IPs** will leave the existing entries unchanged without adding the range.

Saving the range will also allow requests from every other address within it. Only add the range if the entire network should have access.

Duplicate entries and other overlaps with existing addresses or ranges are rejected. Review the existing entries before adding another range. ![ipwhitelist\_replace.png](https://2211217319-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYGsEKyV2Zq4Q8fEJQT40%2Fuploads%2Fgit-blob-3fae76eea49bd874c0b023a3ecc8ba605d97f5af%2Fipwhitelist_replace.png?alt=media)

***

## Remove an entry or disable the whitelist

Click the **Delete** icon next to an entry to remove it. The entry is removed without a confirmation dialog.

If other entries remain, requests must still match one of them. To disable the whitelist, remove every entry. The status changes to **Disabled**.

{% hint style="warning" %}
An empty whitelist allows requests from any IP address; it does not block all requests. A valid [API key](https://docs.cortecs.ai/web-console/api-keys.md) is still required.
{% endhint %}

***

## Troubleshoot blocked requests

If an application is blocked after you activate or change the whitelist:

1. Confirm that its API key belongs to the project whose whitelist you changed.
2. Check the public outbound IP used by the application, including any VPN, proxy, or NAT gateway.
3. Check whether the request uses IPv4 or IPv6 and whether that address matches a saved entry.
4. Ask a project administrator to add the required address or range, then retry the request.

Changing the whitelist does not require creating a new API key.
