API Key Settings

Limit how much your API Key can be used, and from where, via the Security panel on your dashboard. Whether your key sits on a server or in a browser, we strongly recommend setting both a daily and an individual lookup limit.

Setting the right restrictions

There are two approaches to using your API Key within your project. Your Key can either be:

• Private. Lookups are generated from a controlled environment, such as a server belonging to you
• Public. Lookups are generated from a client (e.g. browser or app), which means embedding the Key on the client side

If you will be making requests from within your client's browser, we strongly recommend you create a list of Allowed URLs from which you can make requests.

API Key controls

Control	What it does	When to use it
Daily lookup limits	Caps the lookups your Key can make per day. Resets at midnight	Controlling how much you spend on lookups per day
Individual lookup limits	Caps the lookups one IP address can make per day. Resets for each IP address at midnight	Embedding your Key in client-side code
IP address forwarding	Applies the individual limit to an IP address you forward, rather than the caller's	Requests proxied through a small number of hosts you control
Allowed URLs	Restricts lookups to a list of web addresses	Embedding your Key in client-side code
API Key regeneration	Issues a new Key and stops the old one working	Replacing a Key without affecting your existing purchases
Retention period	Sets how long personal data stays in your transaction logs	Redacting personal data sooner than the 28 day default

Daily lookup limits

A limit on the number of lookups your API Key can make per day.

• This limits the number of postcode lookups on your API Key per day. The limit is reset at midnight.
• This is ideal for controlling the amount you wish to spend on lookups per day.

Your email notification recipients will be notified when you reach 90% or 100% of this cap.

Individual lookup limits

A limit on the number of lookups an individual user can make on your API Key per day.

• This limits the number of daily requests from a specific IP address. The limit is reset for each IP address at midnight.
• This is ideal if you intend on embedding your Key on client side code.

IP address forwarding

Forward the IP address to be rate limited on paid API requests.

When the Daily Individual Lookup Limit is enabled, you may also opt to enable IP Address Forwarding. This will limit requests based on the IP address you provide using an HTTP request header named IDPC-Source-IP. If an address is successfully forwarded, your API response will also contain a IDPC-Source-IP header relaying the rate limited IP address.

Malformed IP addresses passed with the IDPC-Source-IP header will return a 400 response.

• Enable it for integrations that need IP based daily limiting but proxy API requests through a small number of privately controlled hosts. Without it, the IP addresses of the proxies themselves are rate limited rather than the end user.
• Do not enable it for client side integrations. Doing so would let daily rate limiting be circumvented.
• If no header arrives. When IP Address Forwarding is enabled but no IDPC-Source-IP header is provided, the original IP address is limited as usual.

Allowed URLs

A list of web addresses that can perform lookups using your API Key, for example example.com or example.com/users/signup. This is ideal if you intend on embedding your Key on client side code.

Enabling Allowed URLs will also enable CORS.

We strongly recommend restricting by domain and protocol only, for example https://www.example.com. Browsers are deploying increasingly strict defaults when it comes to returning path information on the referer header.

Allowed URLs covers the matching rules in full.

API Key regeneration

You can also generate a new Key through API Key Settings. This will not affect your existing purchases. Requests made on your old Key will fail. Please note this is not reversible.

Retention period

Your transaction logs will contain some personal information detailed in our data processing section.

We will periodically redact any logs (older than your retention period) of personal data. This includes IP address, address query and URL referer headers.

By default, this retention period is set at 28 days. You may also set the retention period to 0 if you wish to disable retention of any personal data.

Related guides

• API Key Security: choose the right controls for a frontend or backend integration
• Allowed URLs: how URLs are matched against the Referer and Origin headers
• API Key: where to find your Key and what each Key controls