IP Allowlist

Overview

IP allowlists restrict which IP addresses can use your gateway API keys. Only requests from allowed IPs will be accepted.

Enabling IP Allowlist

1. Navigate to AI Gateway Settings
2. Go to the Security tab
3. Toggle Enable IP Allowlist on
4. Add IP addresses or CIDR ranges
5. Click Save

Warning: Enabling IP allowlist immediately blocks requests from non-listed IPs.

Adding IP Addresses

Single IP

203.0.113.50

CIDR Range

203.0.113.0/24    # 256 IPs: 203.0.113.0 - 203.0.113.255
10.0.0.0/8        # Private network range

IPv6

2001:db8::1
2001:db8::/32

Common Use Cases

Production Servers

Allow only your production server IPs:

# Production servers
203.0.113.10
203.0.113.11
203.0.113.12

# Load balancer
203.0.113.1/32

Vercel Deployments

Vercel uses dynamic IPs. Options:

1. Use Vercel's OIDC (recommended) - Coming soon
2. Disable IP allowlist for Vercel deployments
3. Use Edge Functions with known egress IPs

AWS Lambda

Allow AWS Lambda NAT Gateway IPs:

# Your VPC NAT Gateway IPs
52.1.2.3
52.1.2.4

Office Network

Allow your office IP range:

# Office network
198.51.100.0/24

CI/CD Pipeline

Allow GitHub Actions IPs:

# GitHub Actions (check current list)
# https://api.github.com/meta
140.82.112.0/20
143.55.64.0/20

Per-Key IP Restrictions

Restrict specific keys to specific IPs:

1. Go to Settings > Gateway API Keys
2. Click on a key
3. Under Allowed IPs, add addresses
4. Click Save

This allows different keys for different environments:

Testing IP Allowlist

Before Enabling

Test from your expected IP:

# Check your current IP
curl https://api.transactional.dev/ip
 
# Test API access
curl https://api.transactional.dev/ai/v1/models \
  -H "Authorization: Bearer gw_sk_your_key"

After Enabling

Requests from non-allowed IPs receive:

{
  "error": {
    "code": "ip_not_allowed",
    "message": "Request IP 203.0.113.99 is not in the allowlist",
    "type": "authorization_error"
  }
}

HTTP Status: 403 Forbidden

Dynamic IP Handling

If your servers have dynamic IPs:

Option 1: CIDR Range

Allow a range that covers your dynamic IPs:

# Your ISP's range (may be broad)
198.51.100.0/16

Option 2: VPN or Proxy

Route API traffic through a fixed IP:

# VPN egress IP
203.0.113.100/32

Option 3: Disable Allowlist

For truly dynamic environments, rely on API key security alone.

Monitoring Blocked Requests

View blocked requests in the dashboard:

1. Go to AI Gateway > Requests
2. Filter by Status: Blocked
3. See source IPs that were rejected

Set up alerts for blocked requests:

1. Go to Settings > Alerts
2. Create alert for "Blocked IP Requests > 10/hour"
3. Configure notification channel

Troubleshooting

Locked Out

If you've locked yourself out:

1. Contact support with your organization ID
2. We can temporarily disable the allowlist
3. Add correct IPs and re-enable

IP Not Showing Correctly

Check for proxies/load balancers:

# Check what IP we see
curl https://api.transactional.dev/ip

If behind a proxy, ensure X-Forwarded-For is set correctly.

CIDR Notation Help

Best Practices

1. Start permissive - Add broader ranges initially
2. Monitor before restricting - Check which IPs are making requests
3. Document allowed IPs - Keep a record of why each IP is allowed
4. Review regularly - Remove IPs that are no longer needed
5. Have a backup plan - Know how to disable in emergencies

Next Steps

• API Key Management
• Rate Limiting
• Error Handling