> For the complete documentation index, see [llms.txt](https://docs.ipaware.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ipaware.io/dashboard/integrations.md).

# Whitelist

Control which IP addresses can access your API by maintaining a whitelist of approved IPs. This adds an extra layer of security to your organization.

### Overview

The IP Whitelist feature allows you to:

* Restrict API access to specific IP addresses
* Label IPs for easy identification
* Track when IPs were added
* Manage your whitelist limit based on your plan 

**How it works:**

* Only whitelisted IPs can make API requests
* Requests from non-whitelisted IPs are rejected
* Both IPv4 and IPv6 addresses are supported

***

### Adding IP Addresses

**Steps:**

1. **Open Add Modal**
   * Navigate to the **Whitelist** tab
   * Click **+ Add IP Address**
2. **Enter IP Details**
   * **IP Address:** Enter the IP address
     * IPv4 format: `8.8.8.8`
     * IPv6 format: `2001:4860:4860::8888`
   * **Label (Optional):** Descriptive name (e.g., "Production Server", "Office Network")
3. **Save IP**
   * Click **Add IP**
   * IP appears in the whitelist table immediately
   * API access is granted instantly

> **Tip:** Use labels to identify IPs easily. Include environment, location, or purpose.

#### Checking Your Limit

Before adding IPs, check your available slots:

* View the **Whitelist Limit** card on the Overview tab
* Shows "X / Y IPs used" (e.g., "3 / 50 IPs used")
* Percentage indicator shows utilization **If you've reached your limit:**
* Remove unused IPs
* Upgrade your plan for more slots
* A modal will prevent adding more IPs

***

### Managing Whitelisted IPs

#### Whitelist Table

The table displays all whitelisted IP addresses:

| Column         | Description                            |
| -------------- | -------------------------------------- |
| **IP Address** | The whitelisted IP (IPv4 or IPv6)      |
| **Label**      | Your descriptive label (or "No Label") |
| **Created**    | Date the IP was added                  |
| **Actions**    | Edit and Remove buttons                |

#### Editing an IP

Update the IP address or label: 

**Steps:**

1. Click **Edit** next to the IP
2. Modify the **IP Address** or **Label**
3. Click **Save Changes** 

**Use cases:**

* Correct a typo in the IP
* Update label for clarity
* Change IP when server address changes

#### Removing an IP

Delete an IP from the whitelist: 

**Steps:**

1. Click **Remove** next to the IP
2. Confirm the action 

**Effects:**

* IP is removed immediately
* Requests from this IP will be rejected
* Cannot be undone (must re-add if needed)

> **Warning:** Ensure no active services are using this IP before removing it.

***

### Whitelist Limits by Plan

Different subscription tiers have different IP limits:

| Plan             | IP Limit               |
| ---------------- | ---------------------- |
| **Free Tier**    | 1 IP address           |
| **Pro Monthly**  | 2 IP addresses         |
| **Pro Yearly**   | 5 IP addresses         |
| **Custom Plans** | Varies (contact sales) |

#### Upgrading for More IPs

If you need more IP addresses:

1. Go to the **Billing** tab
2. Select a higher-tier plan
3. Your IP limit increases immediately
4. Add additional IPs as needed

#### Downgrading Impact

> **Important:** When downgrading to a plan with fewer IP slots:
>
> * Oldest IPs exceeding the new limit are automatically deleted
> * You'll see a warning before confirming the downgrade
> * Review your whitelist before downgrading

***

### IP Address Formats

#### IPv4 Addresses

Standard format: `XXX.XXX.XXX.XXX` 

**Examples:**

* `192.168.1.1` - Private network
* `8.8.8.8` - Public DNS server
* `10.0.0.5` - Private network 
* **Valid range:** `0.0.0.0` to `255.255.255.255`

#### IPv6 Addresses

Standard format: Eight groups of four hexadecimal digits 

**Examples:**

* `2001:4860:4860::8888` - Google DNS
* `2001:0db8:85a3:0000:0000:8a2e:0370:7334` - Full format
* `::1` - Localhost (compressed) 
* **Compression:** Leading zeros and consecutive zero groups can be omitted

***

### Finding Your IP Address

#### Current IP

To find the IP address you're currently using, you can use our service: 

* Visit [ipaware.io](https://ipaware.io)

#### Server IP

To find your server's public IP: 

**Cloud Providers:**

* AWS: Check EC2 instance details
* Google Cloud: Check VM instance details
* Azure: Check Virtual Machine overview **Command line (on the server):**

```bash
curl ifconfig.me
```

***

### Best Practices

#### Security

**Whitelist only necessary IPs:**

* Don't add IPs "just in case"
* Remove IPs when no longer needed
* Regularly audit your whitelist **Use specific IPs:**
* Avoid using dynamic IPs when possible
* Use static IPs for production servers
* Document IP ownership 

**Label everything:**

* Always add descriptive labels
* Include environment (prod, staging, dev)
* Note the purpose or owner

#### Organization

**Naming conventions:**

```
[Environment] - [Purpose] - [Location]
Examples:
- "Production - API Server - AWS US-East"
- "Staging - Test Server - Office"
- "Dev - John's Laptop - Remote"
```

**Regular maintenance:**

* Review whitelist monthly
* Remove decommissioned servers
* Update labels as infrastructure changes
* Document IP changes in your change log

#### Monitoring

**Track usage:**

* Note which IPs are actively making requests
* Identify unused IPs
* Monitor for unexpected access attempts 

**Plan ahead:**

* Know your IP limit
* Plan for growth
* Upgrade before hitting limits

***

### Troubleshooting

#### "IP Not Whitelisted" Error

**Symptoms:**

* API requests return 403 Forbidden
* Error message mentions IP whitelist **Solutions:**

1. **Verify your IP:**

   ```bash
   curl ifconfig.me
   ```
2. **Check whitelist:**
   * Ensure your IP is in the whitelist table
   * Verify the IP is exactly correct (no typos)
3. **Check for IP changes:**
   * Your IP may have changed (common with dynamic IPs)
   * Update the whitelist with your new IP
4. **IPv4 vs IPv6:**
   * Ensure you're using the correct IP version
   * Some networks use IPv6 by default

#### Can't Add More IPs

**Reason:** You've reached your plan's IP limit 

**Solutions:**

1. Remove unused IPs
2. Upgrade to a higher-tier plan
3. Consolidate services to use fewer IPs

#### IP Keeps Changing

**Problem:** Dynamic IP addresses change frequently 

**Solutions:**

* **Contact ISP:** Request a static IP address
* **Use VPN:** Route traffic through a static VPN IP
* **Cloud proxy:** Use a cloud service with static IPs
* **Upgrade plan:** Get more IP slots to accommodate changes

#### Wrong IP Added

**Fix:**

1. Click **Edit** next to the IP
2. Correct the IP address
3. Click **Save Changes** 
4. Or remove and re-add with the correct IP.

***

### Advanced Use Cases

#### Multiple Environments

Organize IPs by environment:

```
Production:
- 203.0.113.10 - "Prod - API Server 1"
- 203.0.113.11 - "Prod - API Server 2"
Staging:
- 198.51.100.5 - "Staging - Test Server"
Development:
- 199.0.2.100 - "Dev - Office Network"
```

#### Load Balancers

When using load balancers:

* Whitelist the load balancer's IP, not individual servers
* Label clearly: "Prod - Load Balancer - AWS ELB"
* Update if load balancer IP changes

#### CI/CD Pipelines

For automated testing:

* Whitelist your CI/CD runner IPs
* Label: "CI/CD - GitHub Actions"
* Use static IPs or IP ranges if supported

***

### Permissions Required

To manage the whitelist, you need:

* **Add IPs:** `organization.whitelist.manage`
* **Edit IPs:** `organization.whitelist.manage`
* **Remove IPs:** `organization.whitelist.manage`
* **View whitelist:** `organization.whitelist.view`

***

### Next Steps

* Create API keys to use with whitelisted IPs
* Monitor usage from whitelisted IPs
* Upgrade plan for more IP slots
* Configure roles to control whitelist access