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.

Overview

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:

Diagram of pattern

Tutorial

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

In the steps below, make sure you use the appropriate URL base path:

Environment URL base path
Sandbox (Hello World API only) sandbox.api.service.nhs.uk
Integration test int.api.service.nhs.uk
Production api.service.nhs.uk

For most APIs, our sandbox environment is open-access, so you don’t need to complete these steps for sandbox testing.

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 https://sandbox.api.service.nhs.uk/hello-world/hello/application \
-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: 8 February 2021 3:12 pm