Application-restricted RESTful APIs - API key authentication

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.

Use this pattern when:

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

We do not use it for APIs that involve personal or sensitive data, but use the Application-restricted RESTful API - signed JWT authentication pattern instead.

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:

You can learn how to use this security pattern with our tutorials written in:

• Java
• PHP
• C#

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.

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

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

For more information on testing, see Testing APIs.

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

1. If you do not already have one, create a developer account.
2. Navigate to my developer account and sign in.
3. Select 'Environment access' on my developer account.
4. Select 'Add new application'.
5. Enter the details of your application including application owner and application name to create your new application.
6. Select 'View your new application' to check or edit your application details.
7. Click the 'Edit' button to make a note of the API key. If you are editing the security details for production applications, follow the online instructions to set up mobile authentication. 
8. Click the 'Add APIs' button to add the API you want to use.

For the Hello World (Sandbox) example, you need to select the API "Hello World API - Application Restricted (Sandbox)"

Once you have your API key, you can call the 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:

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