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 "Development" page and clicking on the "API Keys" tile.

Get an API Key

ℹ️ If you need to maintain a large set of API keys automatically you can use our management API.

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.

Another option you can use for client-side keys is to restrict their usage per IP address. This allows you to use your key on your high-traffic website and still know that each individual user can only use a few of your credits. 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. IP address restrictions are required when a key is authorised for use on the localhost domain.