Authentication API Guide
The Authentication API OpenAPI 3.0 technical specification can be found here
It is also available in JSON format
Introduction
Access to many of the DVLA secure APIs requires use of the Authentication API for user authentication and credential management. Some will require only an API Key, whereas others may require a valid JSON Web Token (JWT) in addition as part of a two-step Secure Token Service (STS) authentication process.
- Use this API to obtain a valid JWT by providing a valid username and password combination as part one.
- Use your unique API Key and the JWT in the request to your desired DVLA API.
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.
First Time 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:
- Update their one-time password using the Change Password API to verify their e-mail address
- Retrieve their API key from the automated e-mail sent after verification
- Call the required API using the two-step authentication process
- Renew password and API Key credentials before expiry
If a user does not change their one-time password within the 24-hour 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
Credentials
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 | Initial one time password provided by DVLA during on-boarding. Must be changed within 24 hours 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 |
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 Recovery
- In the event a user forgets their password or does not change it before the 24-hour 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 to request a verification code.
- The user can then supply their username, verification code and new password to the Change Password service to recover their account.
Authenticate User
The Authenticate service returns a JWT ID token for a given username and password.
To consume the API, make an HTTP POST request to the following URL:
https://driver-vehicle-licensing.api.gov.uk/thirdparty-access/v1/authenticate
Body
Include your Username and Password in the request body like so:
{
"userName": "sallydev01",
"password": "ALongExamplePassword"
}
Example
Using cURL, a request can be made as follows:
curl -X POST -d '{
"userName": "REPLACE WITH YOUR USERNAME",
"password": "REPLACE WITH YOUR PASSWORD"
}' https://driver-vehicle-licensing.api.gov.uk/thirdparty-access/v1/authenticate \
-H 'Content-Type: application/json' -H 'Accept: application/json'
OWASP security guidelines dictate that sensitive information should not be included in URLs. This reduces the risk of sensitive information being unnecessarily recorded in Web Server logs. The vehicle registration number is deemed sensitive information in accordance with the Information Commissioner’s Office (ICO), so is passed in the body as a POST request.
More code examples for this request can be found here.
Response
A successful request should return a JSON response like the one below, containing the JWT string required to be passed into subsequent API calls:
{
"id-token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IlNhbGx5IERldiIsImlhdCI6MTUxNjIzOTAyMn0.G9FgN-Ox0Q8vAQ2D0VEt9FLEeE8oeBjx4l8r07dne6I"
}Error Responses
Here is a list of the possible error responses you may receive using this API:
| 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.” }] |
In addition to this, the common errors section gives errors that may be thrown by the surrounding framework.
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.
To consume the API, make an HTTP POST request to the following URL:
https://driver-vehicle-licensing.api.gov.uk/thirdparty-access/v1/new-password
Body
Include your Username and Email Address in the request body like so:
{
"userName": "sallydev01",
"email": "sally.dev@examplemail.com"
}
Example
Using cURL, a request can be made as follows:
curl -X POST -d '{
"userName": "sallydev01",
"email": "sally.dev@examplemail.com"
}' https://driver-vehicle-licensing.api.gov.uk/thirdparty-access/v1/new-password \
-H 'Content-Type: application/json' -H 'Accept: application/json'
OWASP security guidelines dictate that sensitive information should not be included in URLs. This reduces the risk of sensitive information being unnecessarily recorded in Web Server logs. The vehicle registration number is deemed sensitive information in accordance with the Information Commissioner’s Office (ICO), so is passed in the body as a POST request.
More code examples for this request can be found here.
Response
A successful request should return a JSON response like the one below, containing a message informing that either a password verification code or new one-time password is generated and emailed to the user:
{
"message": "Password reset code sent."
}{
"message": "Signup email resent."
}Error Responses
Here is a list of the possible error responses you may receive using this API:
| 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” }] |
In addition to this, the common errors section gives errors that may be thrown by the surrounding framework.
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.
To consume the API, make an HTTP POST request to the following URL:
https://driver-vehicle-licensing.api.gov.uk/thirdparty-access/v1/password
Body
Using Old Password
If the old password is known then the username, old password, new password should be supplied in the request body like so:
{
"userName": "sallydev01",
"password": "AnOldPassword01%",
"newPassword": "ANewPassword404&",
}
Using Verification Code
If a password verification code is being used then the username, verification code and new password should be supplied in the request body like so:
{
"userName": "sallydev01",
"newPassword": "ANewPassword404&",
"verifyCode": "123789"
}
Example
Using cURL, a request can be made as follows:
curl -X POST -d '{
"userName": "REPLACE WITH YOUR USERNAME",
"password": "REPLACE WITH YOUR OLD PASSWORD",
"newPassword": "REPLACE WITH YOUR NEW PASSWORD",
}' https://driver-vehicle-licensing.api.gov.uk/thirdparty-access/v1/password \
-H 'Content-Type: application/json' -H 'Accept: application/json'
OWASP security guidelines dictate that sensitive information should not be included in URLs. This reduces the risk of sensitive information being unnecessarily recorded in Web Server logs. The vehicle registration number is deemed sensitive information in accordance with the Information Commissioner’s Office (ICO), so is passed in the body as a POST request.
More code examples for this request are available:
- Here for changing password using the old password.
- Here for changing a password with a verification code.
Response
A successful request should return an empty response with a Status Code of 200.
Error Responses
Here is a list of the possible error responses you may receive using this API:
| 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, numerical, and special 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” }] |
In addition to this, the common errors section gives errors that may be thrown by the surrounding framework.
Change API Key
Resets an API Key for a given username and password. A new API Key is returned if valid.
To consume the API, make an HTTP POST request to the following URL:
https://driver-vehicle-licensing.api.gov.uk/thirdparty-access/v1/new-api-key
You will first need to authenticate using the Authenticate endpoint to retrieve a valid JWT token before a new API key request can be made.
Header
Include your current API Key and JWT Token in the Headers of this request.
This request has no body
{
"x-api-key": "<API Key>",
"Authorization": "<JWT ID Token>"
}
Example
Using cURL, a request can be made as follows:
curl -X POST https://driver-vehicle-licensing.api.gov.uk/thirdparty-access/v1/new-api-key \
-H 'Accept: application/json'
-H 'x-api-key: REPLACE WITH YOUR CURRENT API KEY'
-H 'Authorization: REPLACE WITH YOUR JWT'
OWASP security guidelines dictate that sensitive information should not be included in URLs. This reduces the risk of sensitive information being unnecessarily recorded in Web Server logs. The vehicle registration number is deemed sensitive information in accordance with the Information Commissioner’s Office (ICO), so is passed in the body as a POST request.
More code examples for this request can be found here.
Response
A successful request should return a JSON response like the one below, containing your new API Key:
{
"newApiKey": "IaMeKjCXjJY4cnR4nd0mAUtO4O4QI8tkUhNTfBUF"
}Error Responses
Here is a list of the possible error responses you may receive using this API:
| 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” }] |
In addition to this, the common errors section gives errors that may be thrown by the surrounding framework.
Examples
Code Examples
A list of code examples can be found here:
Postman Collection
Alternatively, you can use Postman to create and execute requests.
A Postman collection containing examples for the Authentication API can be downloaded here.
Frequently Asked Questions
How often do I need to change my credentials?
You will need to regularly renew your credentials to ensure you account is secure.
- Passwords need to be changed every 90 days
- API keys must be changed every 365 days
You will be given 14 days’ notice before your password expires, and your account is disabled.
What happens if I do not change my credentials?
In the days prior to your credentials expiring, you will be sent automatic notifications to the email address on your account to warn you that the account will be disabled if no action is taken.
My account is disabled, what should I do?
Please contact DVLASecureAccess@dvla.gov.uk to request that your account be reenabled.
How do I change my password?
To change your password, follow the instructions here.
I have forgotten my password, how do I reset it?
To reset your password, first request a new password verification code by following the instructions here.
The password verification code can then be used with to change your password by following the instructions here.
Alternatively, please contact DVLASecureAccess@dvla.gov.uk to request a new temporary password via email.
How do I change my API key?
To change your API key, follow the instructions here.
I have forgotten my API key; how do I get a new one?
Please contact DVLASecureAccess@dvla.gov.uk to request an API key reminder.
Support
Please direct any technical support queries to DVLASecureAccess@dvla.gov.uk and include Authentication API technical query in the subject line.