Skip to main content
Application-restricted RESTful APIs - API key authentication

Learn how to integrate your software with our application-restricted RESTful APIs - using our API key authentication pattern.


This page explains how to integrate your software with our application-restricted RESTful APIs.

In particular, it describes the API key authentication pattern.

For a full list of available patterns, see Security and authorisation.

When to use this pattern

Use this pattern when:

  • accessing an application-restricted RESTful API
  • the API uses API key authentication

How this pattern works

In this pattern, you authenticate your application by including an API key with each API request. The API key is unique to your application.

The following diagram illustrates the pattern:

May or may not be present
May or may not...
Calling Application
Calling Applicati...
Application-Restricted API
include API key
End User
End User
Viewer does not support full SVG 1.1 API key authentication context diagram


You can learn how to use this security pattern with our hands-on application-restricted RESTful API tutorial.

Bear in mind that the tutorial only teaches you the basic flow. You'll also need to read the detailed integration instructions below to understand how to handle error scenarios.

Detailed integration instructions

The following sections explain in detail how to use this security pattern.

Environments and testing

As well as production, we have a number of test environments. In the steps below, make sure you use the appropriate URL base path:

Environment URL base path
Hello World API only (all other sandbox APIs are open access)
Integration test

For more information on testing, see Testing APIs.

Step 1: create an application

To use this pattern, you need to create an application. This gives you access to your API key, which you will need later in the process.

  1. If you don't already have one, create a developer account.
  2. Navigate to my developer account and sign in.
  3. Select 'My applications'.
  4. Select '+ NEW APP'.
  5. Enter details for your application.
  6. In the 'APIs' section, find the API you want to use and activate it by clicking the slider.
  7. Select 'CREATE' to create the application.
  8. Make a note of the API key.

Step 2: call an application-restricted API

Once you have your API key, you can call an application-restricted API.

You need to include the following header in your call:

  • apikey= <your API key from step 1>

Here's an example, using a CURL command:

curl -X GET \
-H "apikey: [your API key from step 1]"

Note: the URL in the above example is for our sandbox environment. For other environments, see Environments.

All being well, you’ll receive an appropriate response from the API, for example:

HTTP Status: 200 
  "message": "Hello application!"

Error scenarios

If there is an issue with your API key, we will return an error response as follows:

Error scenario HTTP status
API key is missing   401 (Unauthorized)
API key is invalid   401 (Unauthorized)

For details of API-specific error conditions, see the relevant API specification in our API catalogue.

Last edited: 14 September 2021 4:38 pm