Skip to main content
Table of contents

Authentication API Description

Introduction

Access to DVLA secure APIs requires use of the Authentication API for user authentication and credential management.

  • Two credentials are required to provide assurance that the correct end user is using the interface - a user password and API Key
  • After completing the on-boarding process, a username and one time password are sent by email to the user. A separate email containing the API Key is sent after the user changes their one time password.
  • The credentials are required to be supplied separately in a two step Secure Token Service (STS) authentication process. The token returned is in the form of a JSON Web Token (JWT) ID Token.
  • HTTPS one-way is used for confidentiality and integrity as well as assuring DVLA is the only recipient
  • The Authentication API, as with other DVLA APIs, are presented running on a fixed IP address
  • The API users will need to be responsible for secure storage and any additional internal transmission of the credentials as well as supplying to the DVLA interface. Separation and reduction of the supply of credentials reduces the risk of them being compromised and they should only be sent as specified
  • Use of STS supports separate submission of credentials, as well as supporting wider federation of security information without repeated re-submission, validation and authorization

This solution requires the API user to securely manage the credentials and transient ID tokens, including periodic secure reset of these credentials. This can be automated without operational outage as necessary.

Credential / Token Description Renewal Requirements
Username Specific to each third party and provided by DVLA after successful on-boarding Fixed - no requirement to renew
Password One time password provided by DVLA during on-boarding. Reset by manufacturer within 7 days before use of API services. Must be at least 8 characters in length and contain upper, lower, numerical and special characters. Special characters refer to the following: ^ $ * . [ ] { } ( ) ? - “ ! @ # % & / \ , > < ’ : ; _ ~ ` Renewal period of 90 days. Can be changed anytime using the Change. Password API Service. Forgotten or expired passwords can be reset using the New Password API Service
API Key Unique to each third party. Initially provided by DVLA during on-boarding after user changes their one time password. Renewed periodically by the third party. A valid API key will need to be provided within each call to corresponding API services Renewal period of 12 months. Can be renewed anytime using the Change API Key API Service
JWT Token Temporary token (short term). A valid JWT token will need to be provided within each call to corresponding API services Valid for a period of one hour. Obtained through the Authenticate API service

API Setup and Usage

A username, one time password, API key and API URLs will be supplied as part of the on-boarding process. The basic steps for a new user to follow are:

  1. Update their one time password using the Change Password API to verify their e-mail address
  2. Retrieve their API key from the automated e-mail sent after verification
  3. Call the required API using the two step authentication process
  4. Renew password and API Key credentials before expiry

In the event that a user does not change their one time password within the 7 day limit, or loses the initial email, they will need to request a new one. This can be done by calling the New Password service, supplying their username and email address.

The two step authentication and credential renewal processes are summarised below, as well as corresponding API Specifications. The interface specification for each corresponding secure API will include the following headers: x-api-key: <Consumer API Key> Authorization: <JWT ID Token>

STS Two Step Authentication Process

  • Request JWT ID token by supplying username and password to the Authenticate service.
    • DVLA returns a JWT token with a 1 hour expiry time
  • Supply the JWT token plus API Key in subsequent calls to a specific API within the expiry time

2_step_auth

Credential Renewal

  • The user password and API key credentials are required to be reset periodically. 14 days before the credentials expire, a daily reminder email will be sent to the provided email address. However the resets are expected to be automated by API Consumers
  • A client can use the JWT expiry period to renew the password without any risk of outage, or just ensure that a new JWT token is used before the next invocation. For API Key changes, a new JWT is required before the next invocation

credential_renewal

Credential Recovery

  • In the event a user forgets their password or does not change it before the 7 day expiry deadline, the New Password service can be used to request a verification code that will be emailed to the user.
  • The user must supply their username and email address to the New Password service in order to request a verification code.
  • The user can then supply their username, verification code and new password to the Change Password service in order to recover their account.

credential_recovery

Authentication API Specification - Overview

OpenAPI Swagger Specification

Each of the Auithentication API resources are defined in the following combined API OpenAPI 3.0 specification file. A number of online and offline tools are available to help view and navigate OpenAPI specifications. Please take care if using online third party test tools and avoid passing credentials through them as they may be stored by the third party.

For more details visit the OpenAPI specification page.
You can also see the swagger file in JSON format.

Usage Plans and Throttling Limits

Individual APIs may have limits on their usage rates in terms of requests per second. This applies to both individual clients and collective usage for all clients. - A client’s limit is set based on the usage plan that the client is subscribed to - As clients access the API at the same time, there is an overall limit on how many requests are allowed per second in order to protect the service Information regarding the rate limits that exist for individual APIs can be found in their accompanying API specification documentation.

These two scenarios will return an HTTP status code of 429 as specified in the common error responses below. 429 errors are returned in as little as 20ms at the DVLA boundary. Any client retry loops should include a small, ideally increasing delay to avoid excessive requests.

Authentication API Specification - Authenticate

The Authenticate service returns a JWT ID token for a given username and password.

Usage

HTTP Method - POST
Request Body - {"userName": "<yourUsername>", "password": "<yourPassword>"} URL - https://driver-vehicle-licensing.api.gov.uk/thirdparty-access/v1/authenticate

Response

The id-token value contained in the response is the JWT string required to be passed into subsequent API calls. Sample JSON responses are as follows: Success Response Body - { "id-token": "ieyJraWQi..." }

Specific Error Response Examples

HTTP Status Error Comments Sample JSON
400 Bad Request Invalid request body [{ "status”: 400, “title”: “Malformed request” }]
400 Bad Request API Key not required [{ “status”: 400, “title”: “Invalid Request”, “detail”: “Authenticate does not require API Key”}]
401 Authentication Failure Supplied username or password was incorrect [{ “status”: 401, “title”: “Authentication Failure”, “detail”: “Supplied username or password was incorrect, or too many incorrect attempts have been made.” }]
401 Authentication Failure User has tried to authenticate before changing their temporary password [{ “status”: 401, “title”: “Authentication Failure”, “detail”: “Please change your temporary password to verify your account.” }]

Authentication API Specification - Change Password

Changes a third party password for a given username, where the supplied old and new passwords are valid. Also allows recovery of a forgotten/expired password by supplying username, a valid new password and a verification code obtained from the email sent by the New Password API.

Usage

HTTP Method - POST
Change Password Request Body - {"userName": "<yourUsername>", "password": "<yourPassword>", "newPassword": "<newPassword>"}
Password Recovery Request Body - {"userName": "<yourUsername>", "verifyCode": "<yourVerificationCode>", "newPassword": "<newPassword>"}
URL - https://driver-vehicle-licensing.api.gov.uk/thirdparty-access/v1/password

Response

The response confirms if the password change has been successful, and if not the reason(s). Sample JSON responses are below:
Success Response - No Body, Header Status Code - 200

Specific Error Responses Examples

HTTP Status Error Comments Sample JSON
400 Bad Request Invalid/missing parameters in request body [{ “status”: 400, “title”: “Invalid Request”, “detail”: “Please supply userName, newPassword and either password or verifyCode”}]
400 Bad Request API Key not required [{ “status”: 400, “title”: “Invalid Request”, “detail”: “Change Password does not require API Key”}]
400 Bad Request Supplied new password does not meet requirements [{ “status”: 400, “title”: “Invalid Request”, “detail”: “Your new and current password cannot be the same.” }]
[{ “status”: 400, “title”: “Invalid Request”, “detail”: “Your new password cannot be the same as any of your last 10 passwords.” }]
[{ “status”: 400, “title”: “Invalid Password”, “detail”: “Supplied new password must be at least 8 characters and contain upper, lower, special and numerical characters.”}]
401 Unauthorized Supplied username or password was incorrect [{ “status”: 401, “title”: “Authentication Failure”, “detail”: “Supplied username or password was incorrect, your temporary password has expired, or too many incorrect attempts have been made. To request a new password, please make a POST API call to /new-password specifying ‘userName’ and 'email’ in the body.” }]
401 Unauthorized Invalid verification code supplied [{ “status”: 401, “title”: “Authentication Failure”, “detail”: “The supplied username or verification code is incorrect.” }]
500 Internal Server Error Unexpected technical error, failed to update password [{ “status”: 500, “title”: “Internal Server Error” }]

Authentication API Specification - New Password

Sends a verification code email to the user which can be used to reset a forgotten/expired password. A new one time password email is sent instead if the user’s account is not yet verified.

Usage

HTTP Method - POST
Request Body - {"userName": "<yourUsername>", "email": "<yourEmailAddress>"}
URL - https://driver-vehicle-licensing.api.gov.uk/thirdparty-access/v1/new-password

Response

If successful, either a password verification code or new one time password is generated and emailed to the user. Sample JSON responses are as follows:
Successful verification code sent response - {"message": "Password reset code sent."}
Successful one time password resent response - {"message": "Signup email resent."}

Specific Error Response Examples

HTTP Status Error Comments Sample JSON
400 Bad Request API Key not required [{ “status”: 400, “title”: “Invalid Request”, “detail”: “New Password does not require API Key”}]
400 Bad Request Username not supplied correctly in body [{ “status”: 400, “title”: “Invalid Request”, “detail”: “Please supply userName” }]
400 Bad Request Email address not supplied correctly in body [{ “status”: 400, “title”: “Invalid Request”, “detail”: “Please supply email” }]
400 Bad Request Supplied userName or email was incorrect [{ “status”: 400, “title”: “Invalid Request”, “detail”: “Incorrect userName or email” }]
500 Internal Server Error Unexpected technical error [{ “status”: 500, “title”: “Internal Server Error” }]

Authentication API Specification - New API Key

Resets an API Key for a given username and password. A new API Key is returned if valid.

Usage

HTTP Method - POST
Request Header - x-api-key: <yourAPIKey>
Request Header - Authorization: <yourJWTIDToken>
URL - https://driver-vehicle-licensing.api.gov.uk/thirdparty-access/v1/new-api-key

Response

A new API Key is returned if successful. Sample JSON responses are as follows:
Success Response Body - {"message": "API Key successfully changed.", "newApiKey": "<newApiKey>"}

Specific Error Response Examples

HTTP Status Error Comments Sample JSON
401 Unauthorized x-api-key and/or Authorization headers either not supplied or incorrect [{ “status”: 401, “title”: “Unauthorized”, “detail”: “API Key or JWT is either not provided, expired or invalid.” }]
500 Internal Server Error Unexpected technical error, failed to update key [{ “status”: 500, “title”: “Internal Server Error” }]

Error Responses

The functional Open API specification referenced above lists the error format and values returned from the API service itself. In addition to this, the common errors section gives errors that may be thrown by the surrounding framework.

Support

Any technical support queries should be directed via email to DVLASecureAccess@dvla.gov.uk and contain Authentication API technical query in the subject line.