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

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 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 token URL will be sent in full with your credentials. 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 }"

Requesting a new client secret

If your client secret is close to expiration, you are able to request renewal of your credentials by sending a request to the /credentials endpoint. You can obtain a new client secret to continue accessing the service.

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"
}

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.