Skip to main content
Table of contents

Authentication API v1.0.7

API to provide user authentication, change password and change API Key services

Click here to see this OpenAPI specification in JSON format.

Base URLs

Email: DVLA API Team

Authenticate User

post__v1_authenticate

POST /v1/authenticate


Parameters

Name In Type Required Restrictions Description
body body AuthRequest true none Request

Example Request

curl -X POST  -d '{
  "userName": "sallydev01",
  "password": "ALongExamplePassword+"
}' https://driver-vehicle-licensing.api.gov.uk/thirdparty-access/v1/authenticate \
 -H 'Content-Type: application/json' -H 'Accept: application/json'

Responses

Status Meaning Description Schema
200 OK Success AuthResponse
400 Bad Request Bad Request MalformedRequestErrors
401 Unauthorized Authentication Failure AuthenticationErrors

Additional common error responses are listed in the Common Error Responses page.

Example Response

200 Response

{
  "id-token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IlNhbGx5IERldiIsImlhdCI6MTUxNjIzOTAyMn0.G9FgN-Ox0Q8vAQ2D0VEt9FLEeE8oeBjx4l8r07dne6I"
}

Change Password

post__v1_password

POST /v1/password

API to support periodic or adhoc password change


Parameters

Name In Type Required Restrictions Description
body body ChangePasswordRequest true none none

Example Request

curl -X POST  -d '{
  "userName": "sallydev01",
  "password": "AnOldPassword01%",
  "newPassword": "ANewPassword404&",
  "verifyCode": "123789"
}' https://driver-vehicle-licensing.api.gov.uk/thirdparty-access/v1/password \
 -H 'Content-Type: application/json' -H 'Accept: application/json'

Responses

Status Meaning Description Schema
200 OK Success Empty
400 Bad Request Bad Request MalformedRequestErrors
401 Unauthorized Unauthorized UnauthorizedErrors
500 Internal Server Error Unable to change password ServerErrors

Additional common error responses are listed in the Common Error Responses page.

Example Response

200 Response

{}

New Password

post__v1_new-password

POST /v1/new-password

API to send password recovery codes to users


Parameters

Name In Type Required Restrictions Description
body body NewPasswordRequest true none none

Example Request

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'

Responses

Status Meaning Description Schema
200 OK Success Empty
400 Bad Request Bad Request MalformedRequestError
401 Unauthorized Unauthorized UnauthorizedErrors
500 Internal Server Error Unable to change password ServerErrors

Additional common error responses are listed in the Common Error Responses page.

Example Response

200 Response

{}

Change API Key

post__v1_new-api-key

POST /v1/new-api-key

API to support periodic or adhoc retrieval of a new API Key. If successful the old API Key will no longer be valid


Parameters

Name In Type Required Restrictions Description
x-api-key header string true none none
Authorization header string true none none

Example Request

curl -X POST  https://driver-vehicle-licensing.api.gov.uk/thirdparty-access/v1/new-api-key \
 -H 'Accept: application/json' -H 'x-api-key: string' -H 'Authorization: string'

Responses

Status Meaning Description Schema
200 OK Success ChangeApiKeyResponse
400 Bad Request Bad request MalformedRequestErrors
401 Unauthorized Unauthorized UnauthorizedErrors
500 Internal Server Error Unable to fetch new API Key, existing API Key remains valid ServerErrors

Additional common error responses are listed in the Common Error Responses page.

Example Response

200 Response

{
  "newApiKey": "IaMeKjCXjJY4cnR4nd0mAUtO4O4QI8tkUhNTfBUF"
}

Schemas

Empty

{}

Empty Schema

Properties

None

AuthRequest

{
  "userName": "sallydev01",
  "password": "ALongExamplePassword+"
}

Properties

Name Type Required Restrictions Description
userName string false none none
password string false none none

AuthResponse

{
  "id-token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IlNhbGx5IERldiIsImlhdCI6MTUxNjIzOTAyMn0.G9FgN-Ox0Q8vAQ2D0VEt9FLEeE8oeBjx4l8r07dne6I"
}

Properties

Name Type Required Restrictions Description
id-token string false none none

ChangePasswordRequest

{
  "userName": "sallydev01",
  "password": "AnOldPassword01%",
  "newPassword": "ANewPassword404&",
  "verifyCode": "123789"
}

Properties

Name Type Required Restrictions Description
userName string false none none
password string false none none
newPassword string false none none
verifyCode string false none none

NewPasswordRequest

{
  "userName": "sallydev01",
  "email": "sally.dev@examplemail.com"
}

Properties

Name Type Required Restrictions Description
userName string false none none
email string false none none

ChangeApiKeyResponse

{
  "newApiKey": "IaMeKjCXjJY4cnR4nd0mAUtO4O4QI8tkUhNTfBUF"
}

Properties

Name Type Required Restrictions Description
newApiKey string false none none

UnauthorizedErrors

[
  {
    "status": "401",
    "code": "401",
    "title": "Unauthorized",
    "detail": "API Key or JWT is either not provided, expired or invalid."
  }
]

An array containing Unauthorized Error objects

Properties

Name Type Required Restrictions Description
anonymous [UnauthorizedError] false none An array containing Unauthorized Error objects

UnauthorizedError

{
  "status": "401",
  "code": "401",
  "title": "Unauthorized",
  "detail": "API Key or JWT is either not provided, expired or invalid."
}

Properties

Name Type Required Restrictions Description
status integer false none none
code integer false none none
title string true none none
detail string false none none

MalformedRequestErrors

[
  {
    "status": "400",
    "code": "400",
    "title": "Malformed request"
  }
]

Properties

Name Type Required Restrictions Description
anonymous [MalformedRequestError] false none none

MalformedRequestError

{
  "status": "400",
  "code": "400",
  "title": "Malformed request"
}

Properties

Name Type Required Restrictions Description
status integer false none none
code integer false none none
title string true none none
detail string false none none

AuthenticationErrors

[
  {
    "status": "401",
    "code": "401",
    "title": "Authentication Failure",
    "detail": "Supplied username or password was incorrect, or too many incorrect attempts have been made."
  }
]

Properties

Name Type Required Restrictions Description
anonymous [AuthenticationError] false none none

AuthenticationError

{
  "status": "401",
  "code": "401",
  "title": "Authentication Failure",
  "detail": "Supplied username or password was incorrect, or too many incorrect attempts have been made."
}

Properties

Name Type Required Restrictions Description
status integer false none none
code integer false none none
title string true none none
detail string false none none

ServerErrors

[
  {
    "status": "500",
    "code": "500",
    "title": "Internal Server Error"
  }
]

Properties

Name Type Required Restrictions Description
anonymous [ServerError] false none none

ServerError

{
  "status": "500",
  "code": "500",
  "title": "Internal Server Error"
}

Properties

Name Type Required Restrictions Description
status integer false none none
code integer false none none
title string true none none
detail string false none none