Once you have an authorisation code, you need to call our token endpoint to exchange it for an access token. This is an HTTP POST to the following endpoint:
https://api.service.nhs.uk/oauth2/token
Note: the above URL is for our production environment. For other environments, see Environments and testing.
You need to include the following query parameters:
Parameter
|
Description
|
grant_type
|
This is the authorization_code
|
client_id
|
Your application's API key
|
client_secret
|
Your application's secret
|
redirect_uri
|
Your application's Callback URL, URL encoded
|
code
|
authorization_code, as received in step 4
|
Here's a complete example, as a CURL command:
curl -X POST -H "content-type:application/x-www-form-urlencoded" --data \
"grant_type=authorization_code\
&client_id=[YOUR-API-KEY]\
&client_secret=[YOUR-SECRET]\
&redirect_uri=[YOUR-CALLBACK-URL]\
&code=[AUTHORIZATION-CODE]" \
https://api.service.nhs.uk/oauth2/token
Note: the URL in the above example is for our production environment. For other environments, see Environments and testing.
You will receive a response with a JSON response body, containing the following fields:
Field
|
Description
|
access_token
|
The access token you use when calling our user-restricted APIs
|
expires_in
|
The time after which the access token will expire, in seconds
|
refresh_token
|
A token for refreshing the access token once it has expired (see step 9 below)
|
refresh_count
|
The number of times the token has been refreshed so far
|
refresh_token_expires_in
|
The time after which the refresh token will expire, in seconds
|
token_type
|
Bearer
|
Here's an example:
{'access_token': 'Sr5PGv19wTEHJdDr2wx2f7IGd0cw',
'expires_in': '599',
'refresh_count': '0',
'refresh_token': '7qvwCqqUUAmzMjRbQyrhdddwBQUJ9vmt',
'refresh_token_expires_in': '35999',
'token_type': 'Bearer'}
Error scenarios
If there are any issues with your call to our token endpoint, we return an error response, as follows:
Error scenario
|
HTTP status
|
Error code
|
Error message
|
Client secret is missing
|
401 (Unauthorized)
|
invalid_request
|
client_secret is missing
|
Client secret is invalid
|
401 (Unauthorized)
|
invalid_client
|
client_id or client_secret is invalid
|
Client ID (API key) is missing
|
401 (Unauthorized)
|
invalid_request
|
client_id is missing
|
Client ID (API key) is invalid
|
401 (Unauthorized)
|
invalid_client
|
client_id or client_secret is invalid
|
Grant type is missing
|
400 (Bad Request)
|
invalid_request
|
grant_type is missing
|
Grant type is invalid
|
400 (Bad Request)
|
unsupported_grant_type
|
grant_type is invalid
|
Redirect URI (Callback URL) is missing
|
400 (Bad Request)
|
invalid_request
|
redirect_uri is missing
|
Redirect URI (Callback URL) is invalid
|
400 (Bad Request)
|
invalid_request
|
redirect_uri is invalid
|
Authorisation code is missing
|
400 (Bad Request)
|
invalid_request
|
authorization_code is missing
|
Authorisation code is invalid
|
400 (Bad Request)
|
invalid_grant
|
authorization_code is invalid
|