IP Restrictions

Add an extra layer of security to your API keys by specifying which IP addresses can use them. Even if a key is compromised, it won’t work from unauthorized locations.

How IP Restrictions Work

When you add IP addresses to an API key:

1. Requests from allowed IPs work normally
2. Requests from other IPs are rejected with a 403 error
3. If no IPs are specified, the key works from anywhere

This is perfect for production servers with known, static IP addresses.

Adding IP Restrictions

When creating a new key

1. Go to Settings → API Keys
2. Click Create New Key
3. Enter a name for your key
4. In the Allowed IPs field, enter your IP addresses
5. Click Create

For existing keys

1. Go to Settings → API Keys
2. Click Edit next to the key
3. Enter IP addresses in the Allowed IPs field
4. Click Save

IP Address Formats

Single IP addresses

Enter individual IP addresses separated by commas:

192.168.1.100, 10.0.0.50, 203.0.113.42

CIDR notation

For IP ranges, use CIDR notation:

192.168.1.0/24

This allows all IPs from 192.168.1.0 to 192.168.1.255.

Common CIDR ranges

Mixed formats

Combine individual IPs and ranges:

192.168.1.100, 10.0.0.0/24, 203.0.113.42

Finding Your Server’s IP

Cloud providers

Most cloud providers show your instance’s public IP in their dashboard:

• AWS: EC2 instance details → Public IPv4 address
• Google Cloud: VM instances → External IP
• DigitalOcean: Droplet details → Public IPv4
• Heroku: Check your dyno’s outbound IP (may vary)

From the command line

# Linux/Mac
curl ifconfig.me

# or
curl api.ipify.org

For dynamic IPs

If your server’s IP changes (like Heroku or serverless):

1. Consider not using IP restrictions for that key
2. Use a proxy with a static IP
3. Use a VPN with a fixed exit IP

Common Setups

Production server only

Restrict your production key to your server’s IP:

203.0.113.100

Multiple servers

For load-balanced setups, add all server IPs:

203.0.113.100, 203.0.113.101, 203.0.113.102

Or use a CIDR range if they’re in sequence:

203.0.113.100/30

Office + Production

Allow both your office and servers:

203.0.113.100, 198.51.100.0/24

Development (no restrictions)

For development keys, leave the field empty to allow any IP. This makes local testing easier.

Error Handling

When a request comes from an unauthorized IP:

Response (403 Forbidden)

{
  "error": "IP address not allowed"
}

Handling in code

const response = await fetch('https://api.truemail.app/v1/verify', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ email })
});

if (response.status === 403) {
  const error = await response.json();
  if (error.error === 'IP address not allowed') {
    console.error('Server IP not in allowlist. Check API key settings.');
  }
}

Troubleshooting

“IP address not allowed” but I added my IP

1. Check for typos: Verify the IP is entered correctly

2. Check your actual IP: Your outbound IP might differ from what you expect

   curl ifconfig.me
   

3. Proxy/NAT issues: If behind a proxy, use the proxy’s outbound IP
4. IPv6 vs IPv4: Make sure you’re using the right format
5. Changes take effect immediately: No delay after saving

My IP keeps changing

Options for dynamic IPs:

1. Don’t use IP restrictions on that particular key
2. Use a different key for dynamic environments
3. Set up a proxy with a static IP
4. Update IPs programmatically (if your provider has an API)

Testing IP restrictions

Before relying on IP restrictions in production:

1. Add your current IP to the allowlist
2. Make a test request (should work)
3. Remove your IP from the allowlist
4. Make another test request (should fail with 403)
5. Re-add your production server IPs

Best Practices

1. Use separate keys for different environments

• Production key: Restricted to production server IPs
• Development key: No restrictions (or restricted to office IP)

2. Document your IPs

Keep a record of which IPs are associated with which keys and why.

3. Update when infrastructure changes

When you add servers or change providers, remember to update IP restrictions.

4. Don’t over-restrict

If you’re not sure which IP will be used, start without restrictions and add them once you confirm the correct IP.

5. Combine with other security measures

IP restrictions are one layer of security. Also:

• Keep keys secret
• Use environment variables
• Rotate keys periodically

Related

• Managing API Keys - Create and manage keys
• API Overview - Authentication basics
• Error Handling - Handle 403 errors