Securing Your API Key

Circumscribing Key Usage

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

1. By requesting URL. A check to see if the request coming from an allowed domain or page
2. By total lookups in a day. A hard daily cap on the number of searches per day
3. 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

1. Limit by Requesting URL

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

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

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 on URL Matching

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

• Whitelisted 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
• Whitelisted strings which exclude http[s]:// will look for positive substring matches, e.g. foo.com/bar will match both https://foo.com/bar and https://app.foo.com/bar
• URL whitelisting 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

2. 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.

3. 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.