We have detected that you are using Internet Explorer to visit this website. Internet Explorer is now being phased out by Microsoft. As a result, NHS Digital no longer supports any version of Internet Explorer for our web-based products, as it involves considerable extra effort and expense, which cannot be justified from public funds. Some features on this site will not work. You should use a modern browser such as Edge, Chrome, Firefox, or Safari. If you have difficulty installing or accessing a different browser, contact your IT support team.
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:
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)||
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.
You need a separate application for each environment.
- If you don't already have one, create a developer account.
- Navigate to my developer account and sign in.
- Select 'My applications'.
- Select '+ NEW APP'.
- Enter details for your application.
- In the 'APIs' section, find the API you want to use and activate it by clicking the slider.
- Select 'CREATE' to create the application.
- 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:
<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:
"message": "Hello application!"
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||
|API key is invalid||
For details of API-specific error conditions, see the relevant API specification in our API catalogue.