# 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[​](#security-options "Direct link to Security Options") ### Limit by Requesting URL[​](#limit-by-requesting-url "Direct link to Limit by Requesting URL") We can check the `Referer` and `Origin` headers of inbound HTTP requests against a list of [Allowed URLs](/docs/guides/allowed-urls.md) 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[​](#notes "Direct link to 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 "Direct link to 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[​](#limit-by-total-lookups-in-a-day "Direct link to Limit by Total Lookups in a Day") Each API Key can [configured be with a hard limit](/docs/guides/api-key-settings.md) 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[​](#limit-by-total-lookups-per-ip-address-in-a-day "Direct link to 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[​](#ip-address-forwarding "Direct link to 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[​](#managing-api-key-settings "Direct link to 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[​](#allow-urls "Direct link to 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. ![Allowed URLs-screenshot](https://img.ideal-postcodes.co.uk/allowed-urls.png) ### Limit the Daily Lookup Usage[​](#limit-the-daily-lookup-usage "Direct link to 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[​](#limit-the-daily-ip-usage "Direct link to 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](https://img.ideal-postcodes.co.uk/daily-lookup-limits.png)