Skip to main content

Authentication

The API uses OAuth 2.0 with the client credentials flow for authentication and authorisation.

When you have completed the registration process you will receive:

  • a client ID
  • a client secret
  • a scope URL
  • an access token URL
  • an API key
Warning

If you do not use your API key for 90 days, it will be revoked.

Authenticating with an access token

Follow these steps to get an access token.

  1. Register to use the API.
  2. Get your client ID, client secret, scope and access token URL from DVSA.
  3. Get your API key from DVSA.
  4. Generate an access token using the steps below.

Generating the token

Access tokens are issued by Microsoft Entra ID (formerly Azure Active Directory).

Use this command to generate the token:

curl --request POST --url 'https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token' --header 'content-type: application/x-www-form-urlencoded' --data grant_type=client_credentials --data client_id=CLIENT_ID_HERE --data client_secret=CLIENT_SECRET_HERE --data scope=https://tapi.dvsa.gov.uk/.default

The full token URL will be sent in the email with your credentials. It contains the tenantID. Access tokens are valid for 60 minutes from issue.

Cache the access token. This will avoid errors caused by too many requests.

You can use the Microsoft Authentication Library (MSAL), which caches and refreshes tokens automatically.

Response body

{
  "token_type": "Bearer",
  "expires_in": 1199,
  "ext_expires_in": 1199,
  "access_token": "issued-access-token"
}

Authorisation headers

Each request to the MOT history API must have the following request headers:

"Authorization": "Bearer { issued access token }"
"X-API-Key": "{ issued api key }"

Managing your client secret

Client secrets expire every 2 years. You will receive an email notification 30 days and 14 days before your client secret expires. You will need to request a new client secret to continue using the API.

Requesting a new client secret

If your client secret is close to expiring, you can use the /credentials endpoint to request a new one.

The request body must contain following properties:

{
  "awsApiKeyValue": "your_existing_api_key_here",
  "email": "user@example.com"
}

Response body example

If the request is successful, you will receive a JSON object as a response. Here is an example of a successful response:

{
  "clientSecret": "your-new-client-secret-value"
}

If you can’t use the /credentials endpoint to request a new client secret, submit a support request

What to do if your client secret expires

If your client secret expires, submit a support request. You will not be able to access the API until our help desk sends you a new client secret.

See more about how to use the /credentials endpoint in the OpenAPI Specification page.

Error scenarios

A list of error code definitions are available.

If you get an error, check your access token and API key are in your request headers.