Authorisation

Application-restricted endpoints

Application-restricted endpoints do not require authorisation from the end user. They do not give access to sensitive personal data.

We use the open standard OAuth 2.0 with the Client Credentials Grant to generate an access token.

If the endpoint requires a scope, your application must include this scope when creating the access token.

Read the API documentation for authorisation rules for specific API endpoints.

The access token lasts for 4 hours. When it expires you must generate a new token.

See the application-restricted endpoint tutorial for a working example.

The example URLs shown below are for the sandbox environment only. In the production environment you should use https://api.service.hmrc.gov.uk

Getting an OAuth 2.0 access token

The authorisation user journey is an important part of our security, and may be changed without notice.

1. Generate an access token

Do this via a POST to our token endpoint.

Include the request parameters in the request body, not as request headers.

Example request

curl -X POST -H "content-type: application/x-www-form-urlencoded" --data \
"client_secret=[YOUR-CLIENT-SECRET]\
&client_id=[YOUR-CLIENT-ID]\
&grant_type=client_credentials\
&scope=[REQUESTED-SCOPE]" \
https://test-api.service.hmrc.gov.uk/oauth/token

Token endpoint request body parameters and descriptions
Parameter	Description
`client_secret`	One of the client secrets for your application.
`client_id`	The Client ID for your application.
`grant_type`	The OAuth 2.0 grant type. For an application-restricted endpoint this must be `client_credentials`
`scope`	A space-delimited list of scopes you want permission to access. A scope is optional for some endpoints. If a scope is required, check the API documentation for details.

The response contains the access token used for calling the APIs.

Example response

{
  "access_token": "QGbWG8KckncuwwD4uYXgWxF4HQvuPmrmUqKgkpQP",
  "token_type": "bearer",
  "expires_in": 14400,
  "scope": "hello"
}

Error scenarios

If there are issues with your call to our token endpoint, we return an HTTP error status.

Any errors not listed are probably not from us. One possible cause is a network access issue, for example, your network might allow GET requests but not POST requests.

The error codes listed are fixed, but the associated error messages may change without notice.

Error scenarios
Error scenario	HTTP status	Error code	Error message
Client ID is missing	`400` (Bad Request)	`invalid_request`	`client_id is required`
Client ID is invalid	`401` (Unauthorized)	`invalid_client`	`invalid client id or secret`
Client Secret is missing	`400` (Bad Request)	`invalid_request`	`client_secret is required`
Client Secret is invalid	`401` (Unauthorized)	`invalid_client`	`invalid client id or secret`
Grant Type is missing	`400` (Bad Request)	`invalid_request`	`grant_type is required`
Grant Type is invalid	`400` (Bad Request)	`invalid_request`	`unsupported grant_type`
Unexpected error occurred	`500` (Internal Server Error)	`server_error`	Various
Scope is invalid	`400` (Bad Request)	`invalid_scope`	`scope is invalid`

2. Call an API

You can now call an API using the access_token we issued. Do this with an Authorization header containing this access_token as an OAuth 2.0 Bearer Token with the correct API scope.

Example request

curl -X GET https://test-api.service.hmrc.gov.uk/hello/application \
-H ‘Accept: application/vnd.hmrc.1.0+json’ \
-H ‘Authorization: Bearer [ACCESS-TOKEN]’

Managing your client secret

Warning Your client_secret is embedded in the source code of your application and may be discoverable.

You should periodically rotate your client_secret to a new value.

We support 5 client_secret values for a single application.

Is this page not working properly? (opens in new tab)