# Whitelist

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ipaware.io/dashboard/integrations.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.