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
Limit by Requesting URL
We can check the
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
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.
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
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 will behave differently depending on whether it's prefixed with the protocol type (
- Allowed strings beginning with
https://will look for matches which start with that string, e.g.
https://foo.comwill match both
- Allowed strings which exclude
http[s]://will look for positive substring matches, e.g.
foo.comwill match both
- Allowed URLs and individual lookup limits are ideal if you decide on embedding your API Key in client-side code
|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
|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
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.
By allowing URLs, requests can only be made on a webpage, unless it has those addresses in the address bar.
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.