API Key Security

In order to mitigate the risk of misuse, usage of your API Key can be controlled in the following ways:

• By requesting URLs. A check to see if the request coming from an allowed domain or page
• By total lookups in a day. A hard, daily cap on the number of searches per day
• By total lookups per IP address in a day. A hard, daily cap an individual IP address can make in a day

For each of the above mitigations keep in mind whether you intend to create a frontend or backend integration.

• Backend Integration. Requests are made from a environment controlled by you, such as your own server
• Frontend Integration. Requests are made a client in an environment you do not control. E.g. web browser or mobile application

Security Options

Limit by Requesting URL

We can check the Referer and Origin headers of inbound HTTP requests against a list of Allowed URLs provided by you.

Each API Key has a configurable list of allowed URLs, accessible via your dashboard.

We recommend restricting by domain and protocol only (e.g. https://www.example.com). Browsers are deploying increasingly strict defaults when it comes to returning path information on the referer header. In other words, opt for https://example.com rather than https://example.com/ or https://example.com/page.

This only works for frontend integrations where the client is a web browser. Should you wish to work in a non-browser environment, the headers may be unset. In such a scenario, you may wish to create a separate API key for staging/development.

Notes

The referer policy of your page will affect whether we can check the Referer header. If Referrer-Policy is enabled, no Referer headers will be sent for no-referrer and same-origin.

If relying on Origin header matching and you wish to match the domain and protocol (e.g. https://google.com), be sure to omit the trailing slash or any path in the URL as the Origin header omits this information as well.

URL Matching

URL matching will behave differently depending on whether it's prefixed with the protocol type (http(s)://).

• Allowed strings beginning with http:// or https:// will look for matches which start with that string, e.g. https://foo.com will match both https://foo.com/ and https://foo.com/bar
• Allowed strings which exclude http[s]:// will look for positive substring matches, e.g. foo.com will match both https://bar.foo.com and http://bar.foo.com
• Allowed URLs and individual lookup limits are ideal if you decide on embedding your API Key in client-side code

Lookup Limit	Description
Daily	Limits the number of requests made on your API Key per day. Limit is reset at midnight. Email is sent to the notification list when 90% or 100% of the cap is reached
Individual	Limits the number of requests made on your API Key from a specific IP address. Limit is reset for each IP address at midnight

Limit by Total Lookups in a Day

Each API Key can configured be with a hard limit amounting to the total number of allowed lookups per day.

The API Key notification list will be emailed when you reach 90% and 100% of this cap.

This can be used in both frontend and backend integrations.

Limit by Total Lookups per IP Address in a Day

Each API Key can limit the number of lookups an individual IP address can make in a day.

This can be used in both frontend and backend integrations. However, backend integrations require IP address forwarding enabled.

IP Address Forwarding

For backend integrations you can also enable a per IP address daily limit to your API key if you forward your user's IP Address to us, using the custom request header IDPC-Source-IP.

Following a successful forward, your response will also contain a IDPC-Source-IP header carrying the rate limited IP address.

Malformed IP addresses passed with the IDPC-Source-IP header will result in a 400 response code.

If IP Address Forwarding is enabled, but no IDPC-Source-IP header is provided, then the original IP address will be limited.

IP Address Forwarding should not be permitted for client-side integrations as this would circumvent daily rate limiting.

Managing API Key Settings

To do this on your dashboard, click on the blue "Manage" button on your API key. Scroll down to Key Restrictions. Here, you can configure the below settings.

Allow URLs

By allowing URLs, requests can only be made on a webpage, unless it has those addresses in the address bar.

Under Allowed URLs enter the addresses.

Limit the Daily Lookup Usage

You can set a hard daily cap on the number of searches that can be made on your website or application.

We recommend setting it to ten times your daily peak.

Limit the Daily IP Usage

You can set a hard daily cap on the number of searches an individual IP address can make in a day.