API Key Best Practices


How to secure your API Key

What is an API Key?

The API key is the credential to identify the website or application that's making a call to an API.

When an account is created, a unique API Key is generated. Using an API Key enables usage information to be associated with the account.


Protecting your API Key

You should secure the API Key in your website or application to avoid unexpected charges on your account.

You can secure your API Key by designating restrictions and by implementing best practices that are appropriate for your use case.

  • Monitor usage of your API for anomalies. If you obverse unauthorised usage or unexpected excessive usage, please get in contact with us and we will help you to investigate further.
  • Apply an API restriction on the API Key. This action narrows the scope of the API Key.

How to restrict an API Key

The API Key is your unique credential that you should manage carefully. At a minimum, follow the recommendations below to keep your key safe, and to make sure that you have restrictions in place to reduce the impact of a compromised API Key.

Visit the account page to configure restrictions for an API Key.

  • Domains (HTTP referrers)
    • Accept requests from the list of websites that you supply.
    • Wildcard characters are acceptable for naming similar websites. For example, *.addy.co.nz accepts all sites ending with addy.co.nz, such as www.addy.co.nz
    • This option is ideal when you have a public facing website.
  • IP Addresses
    • Accept requests from the list of IP v4 web server IP addresses that you supply.
    • This option is ideal when calling the API behind a proxy or reverse proxy.
    • This option should not be used for public facing websites as the client's IP address will be unknown.
  • Secret
    • Use the API Key and the API Secret within an application to call the API.
    • The secret should never be disclosed to end-users.
    • This option is ideal when calling the API from an application, behind a firewall or when the HTTP referer header's originating domain is not included in the API call.

Security Workflow

The diagram below illustrates the authorisation flow using an API Key, API Secret, Domain (HTTP referrers) and IP Addresses.


API Security Workflow