Skip to main content

API Key Security

Usage of your API Key can be controlled three ways: by the URL a request comes from, by total lookups in a day and by total lookups per IP address in a day. Which of them you reach for depends on where your integration runs.

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

Security options​

ControlWhat it checksFrontendBackend
Limit by requesting URLThe Referer and Origin headers against a list of Allowed URLs you provideYesNo, the headers may be unset outside a browser
Limit by total lookups in a dayA hard daily cap on lookups made on the KeyYesYes
Limit by total lookups per IP address in a dayA hard daily cap on lookups from one IP addressYesYes, with IP Address Forwarding enabled

Allowed URLs and individual lookup limits are ideal if you decide on embedding your API Key in client-side code.

Limit by requesting URL​

We 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, accessible via your dashboard.

We 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. 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 and development.

URL matching​

Allowed URLs covers how each URL format is matched, and how your page's referrer policy affects whether we see a Referer header at all.

Limit by total lookups in a day​

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

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. The limit is reset for each IP address at midnight.

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.

  • On a successful forward. Your response will also contain a IDPC-Source-IP header carrying the rate limited IP address.
  • On a malformed address. Malformed IP addresses passed with the IDPC-Source-IP header will result in a 400 response code.
  • When the header is absent. If IP Address Forwarding is enabled but no IDPC-Source-IP header is provided, the original IP address will be limited.
  • In your logs. The forwarded address is recorded against the lookup and appears in the final column of your Key's usage log CSV. It is subject to the same redaction window as the rest of the personal data in that log.

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

Managing API Key Settings​

Click the blue Manage button on your API Key, then scroll down to Key Restrictions. Here you can configure the settings below.

Allow URLs​

Restrict your API Key so that only the web addresses you list can make requests on it.

Under Allowed URLs, enter the addresses.

Allowed URLs screenshot

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.

Daily lookup limits screenshot

  • Allowed URLs: the matching rules, and the header behaviour behind them
  • API Key Settings: every control on a Key, including log retention and Key regeneration
  • API Key: where to find your Key and what each Key controls