API Keys
Use an API Key to authenticate web service calls.
Introduction
An API key is a unique code that can be used to authenticate web service API calls against your account without also giving access to your username and password. Each user can generate multiple API keys and associate different restrictions with each key, giving much more flexibility than using the username and password directly.
Generating API Keys
API Keys can be generated from the Dashboard by navigating to the "Validation" tab and clicking on the "API Keys" tile.
When creating a new API Key, you will need to choose whether you will be using the key from server- or client-side code.
Server-Side API Keys
When using an API Key from server-side code, you can choose to restrict the use of the key from particular IP addresses or IP address ranges. As server-side code is typically run from a fixed IP address, this is an effective way of keeping your account secure.
If you are using the SOAP API for calling a service, you can use the API Key for authentication by prefixing it with apikey- and passing it as the username parameter, while leaving the password parameter blank. For example, see the following C# code:
var apiKey = "ABCD-EFGH-1234-5678"; var proxy = new AddressCaptureSoapClient(); var result = proxy.GetFullAddress("apikey-" + apiKey, null, postcode, building, null);
If you are using the JSON API, simply include the API Key in the URL as a key parameter, e.g.:
https://webservices.data-8.co.uk/AddressCapture/GetFullAddress.json?key=ABCD-EFGH-1234-5678
Client-Side API Keys
When using an API Key from client-side code, you can still choose to restrict the key to specific IP addresses, as for server-side keys. This is primarily useful if you are developing an Intranet application.
You must also specify the domain names that the key can be used on. This should be set to the domain name only, so if you want to use the page on https://www.test.com/contact-us, you would enter the domain name www.test.com
If you are testing your web application using the localhost domain name, you must authorise your key for that name. It is not allowed to combine the use of localhost with other domain names though, so you must then generate a second key for use on your live site and change the key that is used in your website configuration file or database during your deployment process.
Protecting against abuse of client-side API keys
When you embed a client-side API key into your web page, you are making those credentials available to anyone with access to that page. This allows the users of your website to make requests to our services as part of the functionality of your site, but this can also be abused, leading to your credits being consumed by unrelated third parties.
We use industry-standard techniques to ensure that requests using your API key are in fact coming from a website that you have authorised the key for, but this is not infallible.
One key protection against this is to limit the number of requests that your API key can be used per IP address per day. By setting this limit higher than the number of requests a regular user should need to make this should not impact legitimate use, but limits the exposure of your account to abuse.
Be careful when enabling this option however, as if you have a lot of users behind a corporate firewall it's likely that they will all have the same public IP address and therefore will share the same total limit on the number of requests that they can make.
You can also restrict which IP addresses can use your key. This is not applicable when you have a public website that could be used from anywhere, but if you are building an Intranet site that you are expecting only to be accessed from your local network this will block any unauthorised use of your key from elsewhere. IP address restrictions are required when a key is authorised for use on the localhost domain.
If you would like more control over access to our services from client-side code, you make prefer to use JWT authentication instead.