Use an API Key to authenticate web service calls.
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.:
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
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
The number of returned mail reduced by 28% as a result of the integrated reference to the goneaway fileBusiness Strategy Manager, Brookson Ltd