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

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 \

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 \
-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.