https://docs.addresszen.com/assets/js/26cc9dae.d992bb36.js

1"use strict";(globalThis.webpackChunk_atlas_docs_zen=globalThis.webpackChunk_atlas_docs_zen||[]).push([[7460],{4056(e,s,i){i.d(s,{R:()=>t,x:()=>o});var n=i(2155);const r={},d=n.createContext(r);function t(e){const s=n.useContext(d);return n.useMemo(function(){return"function"==typeof e?e(s):{...s,...e}},[s,e])}function o(e){let s;return s=e.disableParentContext?"function"==typeof e.components?e.components(r):e.components||r:t(e.components),n.createElement(d.Provider,{value:s},e.children)}},4523(e,s,i){i.r(s),i.d(s,{assets:()=>a,contentTitle:()=>o,default:()=>h,frontMatter:()=>t,metadata:()=>n,toc:()=>l});const n=JSON.parse('{"id":"guides/api-key-secure","title":"API Key Security","description":"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.","source":"@site/docs/guides/api-key-secure.mdx","sourceDirName":"guides","slug":"/guides/api-key-secure","permalink":"/docs/guides/api-key-secure","draft":false,"unlisted":false,"tags":[],"version":"current","frontMatter":{"title":"API Key Security","sidebar_label":"API Key Security"},"sidebar":"guides","previous":{"title":"API Key Settings","permalink":"/docs/guides/api-key-settings"},"next":{"title":"Allowed URLs","permalink":"/docs/guides/allowed-urls"}}');var r=i(5723),d=i(4056);const t={title:"API Key Security",sidebar_label:"API Key Security"},o=void 0,a={},l=[{value:"Security options",id:"security-options",level:2},{value:"Limit by requesting URL",id:"limit-by-requesting-url",level:3},{value:"URL matching",id:"url-matching",level:4},{value:"Limit by total lookups in a day",id:"limit-by-total-lookups-in-a-day",level:3},{value:"Limit by total lookups per IP address in a day",id:"limit-by-total-lookups-per-ip-address-in-a-day",level:3},{value:"IP Address Forwarding",id:"ip-address-forwarding",level:4},{value:"Managing API Key Settings",id:"managing-api-key-settings",level:2},{value:"Allow URLs",id:"allow-urls",level:3},{value:"Limit the daily lookup usage",id:"limit-the-daily-lookup-usage",level:3},{value:"Limit the daily IP usage",id:"limit-the-daily-ip-usage",level:3},{value:"Related guides",id:"related-guides",level:2}];function c(e){const s={a:"a",code:"code",h2:"h2",h3:"h3",h4:"h4",img:"img",li:"li",p:"p",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,d.R)(),...e.components};return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(s.p,{children:"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."}),"\n",(0,r.jsxs)(s.ul,{children:["\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.strong,{children:"Frontend integration."})," Requests are made from a client in an environment you do not control, e.g. a web browser or mobile application"]}),"\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.strong,{children:"Backend integration."})," Requests are made from an environment controlled by you, such as your own server"]}),"\n"]}),"\n",(0,r.jsx)(s.h2,{id:"security-options",children:"Security options"}),"\n",(0,r.jsxs)(s.table,{children:[(0,r.jsx)(s.thead,{children:(0,r.jsxs)(s.tr,{children:[(0,r.jsx)(s.th,{children:"Control"}),(0,r.jsx)(s.th,{children:"What it checks"}),(0,r.jsx)(s.th,{children:"Frontend"}),(0,r.jsx)(s.th,{children:"Backend"})]})}),(0,r.jsxs)(s.tbody,{children:[(0,r.jsxs)(s.tr,{children:[(0,r.jsx)(s.td,{children:(0,r.jsx)(s.a,{href:"#limit-by-requesting-url",children:"Limit by requesting URL"})}),(0,r.jsxs)(s.td,{children:["The ",(0,r.jsx)(s.code,{children:"Referer"})," and ",(0,r.jsx)(s.code,{children:"Origin"})," headers against a list of Allowed URLs you provide"]}),(0,r.jsx)(s.td,{children:"Yes"}),(0,r.jsx)(s.td,{children:"No, the headers may be unset outside a browser"})]}),(0,r.jsxs)(s.tr,{children:[(0,r.jsx)(s.td,{children:(0,r.jsx)(s.a,{href:"#limit-by-total-lookups-in-a-day",children:"Limit by total lookups in a day"})}),(0,r.jsx)(s.td,{children:"A hard daily cap on lookups made on the Key"}),(0,r.jsx)(s.td,{children:"Yes"}),(0,r.jsx)(s.td,{children:"Yes"})]}),(0,r.jsxs)(s.tr,{children:[(0,r.jsx)(s.td,{children:(0,r.jsx)(s.a,{href:"#limit-by-total-lookups-per-ip-address-in-a-day",children:"Limit by total lookups per IP address in a day"})}),(0,r.jsx)(s.td,{children:"A hard daily cap on lookups from one IP address"}),(0,r.jsx)(s.td,{children:"Yes"}),(0,r.jsx)(s.td,{children:"Yes, with IP Address Forwarding enabled"})]})]})]}),"\n",(0,r.jsx)(s.p,{children:"Allowed URLs and individual lookup limits are ideal if you decide on embedding your API Key in client-side code."}),"\n",(0,r.jsx)(s.h3,{id:"limit-by-requesting-url",children:"Limit by requesting URL"}),"\n",(0,r.jsxs)(s.p,{children:["We check the ",(0,r.jsx)(s.code,{children:"Referer"})," and ",(0,r.jsx)(s.code,{children:"Origin"})," headers of inbound HTTP requests against a list of ",(0,r.jsx)(s.a,{href:"/docs/guides/allowed-urls",children:"Allowed URLs"})," provided by you. Each API Key has a configurable list, accessible via your dashboard."]}),"\n",(0,r.jsxs)(s.p,{children:[(0,r.jsx)(s.strong,{children:"We recommend"})," restricting by domain and protocol only, for example ",(0,r.jsx)(s.code,{children:"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 ",(0,r.jsx)(s.code,{children:"https://example.com"})," rather than ",(0,r.jsx)(s.code,{children:"https://example.com/"})," or ",(0,r.jsx)(s.code,{children:"https://example.com/page"}),"."]}),"\n",(0,r.jsxs)(s.p,{children:["This only works for ",(0,r.jsx)(s.strong,{children:"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 sce

1nario, you may wish to create a separate API Key for staging and development."]}),"\n",(0,r.jsx)(s.h4,{id:"url-matching",children:"URL matching"}),"\n",(0,r.jsxs)(s.p,{children:[(0,r.jsx)(s.a,{href:"/docs/guides/allowed-urls",children:"Allowed URLs"})," covers how each URL format is matched, and how your page's referrer policy affects whether we see a ",(0,r.jsx)(s.code,{children:"Referer"})," header at all."]}),"\n",(0,r.jsx)(s.h3,{id:"limit-by-total-lookups-in-a-day",children:"Limit by total lookups in a day"}),"\n",(0,r.jsxs)(s.p,{children:["Each API Key can be ",(0,r.jsx)(s.a,{href:"/docs/guides/api-key-settings",children:"configured with a hard limit"})," amounting to the total number of allowed lookups per day. The limit is reset at midnight."]}),"\n",(0,r.jsx)(s.p,{children:"The API Key notification list will be emailed when you reach 90% and 100% of this cap."}),"\n",(0,r.jsxs)(s.p,{children:["This can be used in both ",(0,r.jsx)(s.strong,{children:"frontend"})," and ",(0,r.jsx)(s.strong,{children:"backend"})," integrations."]}),"\n",(0,r.jsx)(s.h3,{id:"limit-by-total-lookups-per-ip-address-in-a-day",children:"Limit by total lookups per IP address in a day"}),"\n",(0,r.jsx)(s.p,{children:"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."}),"\n",(0,r.jsxs)(s.p,{children:["This can be used in both ",(0,r.jsx)(s.strong,{children:"frontend"})," and ",(0,r.jsx)(s.strong,{children:"backend"})," integrations. However, ",(0,r.jsx)(s.strong,{children:"backend"})," integrations require IP address forwarding enabled."]}),"\n",(0,r.jsx)(s.h4,{id:"ip-address-forwarding",children:"IP Address Forwarding"}),"\n",(0,r.jsxs)(s.p,{children:["For ",(0,r.jsx)(s.strong,{children:"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 ",(0,r.jsx)(s.code,{children:"IDPC-Source-IP"}),"."]}),"\n",(0,r.jsxs)(s.ul,{children:["\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.strong,{children:"On a successful forward."})," Your response will also contain a ",(0,r.jsx)(s.code,{children:"IDPC-Source-IP"})," header carrying the rate limited IP address."]}),"\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.strong,{children:"On a malformed address."})," Malformed IP addresses passed with the ",(0,r.jsx)(s.code,{children:"IDPC-Source-IP"})," header will result in a ",(0,r.jsx)(s.code,{children:"400"})," response code."]}),"\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.strong,{children:"When the header is absent."})," If IP Address Forwarding is enabled but no ",(0,r.jsx)(s.code,{children:"IDPC-Source-IP"})," header is provided, the original IP address will be limited."]}),"\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.strong,{children:"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."]}),"\n"]}),"\n",(0,r.jsxs)(s.p,{children:["IP Address Forwarding ",(0,r.jsx)(s.strong,{children:"should not"})," be permitted for client-side integrations as this would circumvent daily rate limiting."]}),"\n",(0,r.jsx)(s.h2,{id:"managing-api-key-settings",children:"Managing API Key Settings"}),"\n",(0,r.jsxs)(s.p,{children:["Click the blue ",(0,r.jsx)(s.code,{children:"Manage"})," button on your API Key, then scroll down to ",(0,r.jsx)(s.code,{children:"Key Restrictions"}),". Here you can configure the settings below."]}),"\n",(0,r.jsx)(s.h3,{id:"allow-urls",children:"Allow URLs"}),"\n",(0,r.jsx)(s.p,{children:"Restrict your API Key so that only the web addresses you list can make requests on it."}),"\n",(0,r.jsxs)(s.p,{children:["Under ",(0,r.jsx)(s.code,{children:"Allowed URLs"}),", enter the addresses."]}),"\n",(0,r.jsx)(s.p,{children:(0,r.jsx)(s.img,{src:"https://img.ideal-postcodes.co.uk/allowed-urls.png",alt:"Allowed URLs screenshot"})}),"\n",(0,r.jsx)(s.h3,{id:"limit-the-daily-lookup-usage",children:"Limit the daily lookup usage"}),"\n",(0,r.jsx)(s.p,{children:"You can set a hard daily cap on the number of searches that can be made on your website or application."}),"\n",(0,r.jsx)(s.p,{children:"We recommend setting it to ten times your daily peak."}),"\n",(0,r.jsx)(s.h3,{id:"limit-the-daily-ip-usage",children:"Limit the daily IP usage"}),"\n",(0,r.jsx)(s.p,{children:"You can set a hard daily cap on the number of searches an individual IP address can make in a day."}),"\n",(0,r.jsx)(s.p,{children:(0,r.jsx)(s.img,{src:"https://img.ideal-postcodes.co.uk/daily-lookup-limits.png",alt:"Daily lookup limits screenshot"})}),"\n",(0,r.jsx)(s.h2,{id:"related-guides",children:"Related guides"}),"\n",(0,r.jsxs)(s.ul,{children:["\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.a,{href:"/docs/guides/allowed-urls",children:"Allowed URLs"}),": the matching rules, and the header behaviour behind them"]}),"\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.a,{href:"/docs/guides/api-key-settings",children:"API Key Settings"}),": every control on a Key, including log retention and Key regeneration"]}),"\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.a,{href:"/docs/guides/api-key",children:"API Key"}),": where to find your Key and what each Key controls"]}

1),"\n"]})]})}function h(e={}){const{wrapper:s}={...(0,d.R)(),...e.components};return s?(0,r.jsx)(s,{...e,children:(0,r.jsx)(c,{...e})}):c(e)}}}]);