Restrict API Keys by IP Address

Limit which IP addresses can make API calls with a key

You can add an IP allowlist to any API key. Once a key has an allowlist, the Versium APIs only accept requests made with that key from the IP addresses on the list. Requests from any other address are rejected, even when the key itself is valid.

By default a key has no allowlist and can be used from any IP address.

Add an IP allowlist to an API Key

  1. Log in and go the Versium REACH.
  2. On top right click on your account name and then Settings
  3. In the Settings page click Manage API Keys
  4. In the section All API Keys, under the Actions field, click on the 3-vertical-dots beside the Key
  5. Click on Restrict by IP
  6. In the text area, enter the IP addresses or CIDR ranges that are allowed to use this key, separated by commas. For example: 203.0.113.10, 198.51.100.0/24
  7. Click Submit

To change the allowlist later, open Restrict by IP again, edit the list, and click Submit. The list you submit replaces the previous one.

Remove an IP allowlist

  1. Open Restrict by IP for the key, as described above.
  2. Clear all entries from the text area so it is empty.
  3. Click Submit

The key can then be used from any IP address again.

How the allowlist works

  • IPv4 addresses and CIDR ranges -- Each entry must be either a complete IPv4 address, such as 203.0.113.25, or an IPv4 range in CIDR notation, such as 203.0.113.0/24 (which covers 203.0.113.0 through 203.0.113.255). A request is allowed if its IP address matches any single address on the list or falls inside any range on the list. Wildcards such as 203.0.113.* are not supported; use a CIDR range instead.
  • Use your public IP address -- The allowlist is checked against the IP address your request comes from as seen by Versium, which is usually the public (outbound) IP address of your server, office network, or NAT gateway, not a private address like 10.x.x.x or 192.168.x.x.
  • IPv6 is not supported -- If a key has an allowlist, requests that reach Versium over IPv6 are rejected. Make sure the systems calling the API connect over IPv4.
  • Applies to all API calls made with the key -- The allowlist is checked on every request made with the key, including append, list generation, and batch job requests.
  • Each key has its own allowlist -- An allowlist on one key does not affect your other keys. You can use separate keys for systems with different IP addresses.
🚧

Check your IP addresses before you save

Once you save an allowlist, any system that uses the key from an address not on the list stops working right away. If your servers' outbound IP addresses can change (for example, with some cloud hosting or serverless platforms), set up a static outbound IP address first.

Requests from IP addresses that are not allowed

If a request is made from an IP address that is not on the key's allowlist, the API returns HTTP status 401 Unauthorized with this error:

{
  "versium": {
    "errors": ["Request sent from invalid IP."]
  }
}

The response may include other fields depending on the API. If you see this error, confirm the public IP address of the system making the request and add it to the key's allowlist.