This version is in beta - expect some breaking changes.

Agent Authorisation API

Dates and amounts
Date Amount
Version and status
Available in Sandbox Yes
Sandbox base URL https://test-api.service.hmrc.gov.uk
Available in Production Yes
Production base URL https://api.service.hmrc.gov.uk

Overview

This API allows tax agents to request authorisation to act on a client's behalf for a specific Making Tax Digital (MTD) tax service and have the option to cancel the authorisation request.

The API also allows the agent to check the status of authorisations already requested and query active or inactive relationships.

This API has no effect on the existing XML API.

Change Log

You can find the changelog in the agent-authorisation-api GitHub repository.

Why use this API?

Agents often use software to perform services for their clients. The API will benefit these agents as it allows them to create a request for authorisation to act on a client's behalf for a specific Making Tax Digital service directly through software.

This process involves the agent providing their own personal identifier and some information about the client that they wish to act on behalf of. This generates a link that the agent can send to their client. The client can then follow this link to authorise the agent for a service.

This API will save an agent time as they currently need to use an Agent Services user interface to create an authorisation request using their agent services account.

Usage scenario

The aim is for the API to mirror the current process that happens through the Agent Services user interface:

  • An agent uses a third-party application or software to request a new authorisation
  • An agent identifier - the Agent Reference Number (ARN) - is passed to the API
  • The agent enters the service they are requesting access to, for example, sending Income Tax updates through software (MTD-IT) or sending VAT Returns through software (MTD-VAT)
  • The agent enters the identifier for the client they are requesting authorisation from, for example:
    • National Insurance number (NINO)
    • VAT registration number (VRN)
  • If required by the service the agent enters an additional identifier for the client, for example, the client's postcode or VAT registration date
  • The API returns a link for the client to follow to authorise the agent and the date when the authorisation request will expire
  • The agent sends the link to the client they wish to act on behalf of
  • If the agent changes their mind, they can cancel the authorisation request as long as the client has not responded to it
  • The client accesses the link and signs in using their a Government Gateway login details to accept the agent's request
  • The agent can check if they have been authorised by a client.

The detailed guide how to create required client data in the External Tests (Sandbox) environment can be found at https://test-www.tax.service.gov.uk/agents-external-stubs/help/agent-authorisation-api

Versioning

When an API changes in a way that is backwards-incompatible, we increase the version number of the API. See our reference guide for more on versioning.

Errors

We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:

  • 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action
  • 400 to 499 if it failed because of a client error by your application
  • 500 to 599 if it failed because of an error on our server

Errors specific to each API are shown in the Endpoints section, under Response. See our reference guide for more on errors.

Skip to main content

Endpoints

/agents/{arn}/invitations

Get all authorisation requests for the last 30 days
GET

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:sent-invitations scope.

Path parameters

Path parameters table
Name Description
arn
string
required

The Making Tax Digital (MTD) platform Agent Reference Number. For format and validation of Agent Reference Number See here

For example: AARN9999999

Request headers

Request headers Table
Name Description
Accept
required

Specifies the response format and the version of the API to be used.

For example: application/vnd.hmrc.1.0+json
Authorization
required
An OAuth 2.0 Bearer Token with the read:sent-invitations scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Response

HTTP status: 200 (OK)

[{
  "_links": {
    "self": {
      "href": "/agents/AARN9999999/invitations/CS5AK7O8FPC43"
    }
  },
  "created": "2019-01-21T14:27:44.620Z",
  "arn": "AARN9999999",
  "service": ["MTD-IT"],
  "status": "Pending",
  "expiresOn": "2019-02-04T00:00:00:000Z",
  "clientActionUrl": "https://www.tax.service.gov.uk/invitations/personal/12345678/agent-1"
},
  {
    "_links": {
      "self": {
        "href": "/agents/AARN9999999/invitations/CS5AK7O8FPC43"
      }
    },
    "created": "2019-01-21T14:27:44.620Z",
    "arn": "AARN9999999",
    "service": ["MTD-IT"],
    "status": "Accepted",
    "updated": "2019-01-21T14:27:44.620Z"
  }
]

Response

HTTP status: 204 (No Content)

Response table
Name Description
_links
object
required

No description available.

self
object
required

A link to the current resource.

href
string
required

No description available.

service
array
required

What do you want the client to authorise you to do?

Limited to the following possible values:

MTD-IT - Report income or expenses through software
MTD-VAT - Report their VAT returns through software
arn
string
required

The Agent Registration Number for the calling agency

created
string
required

Creation time of the request (RFC3339 / ISO8601 format)

updated
string
optional

Update time of the request (RFC3339 / ISO8601 format)

expiresOn
string
optional

Expiration time of the request (RFC3339 / ISO8601 format)

status
string
required

The current status of the invitation

Limited to the following possible values:

Pending - The invitation has been created, it has not been accepted or rejected by the client. Only the service can set this status.
Accepted - The client has accepted the invitation. Only the client can set this status.
Rejected - The client has rejected the invitation. Only the client can set this status.
Cancelled - The agency has cancelled the invitation. Only the agency can set this status.
Expired - Client did not respond to the Agent's Invitation within 14 days. Only the service can set this status.
clientActionUrl
string
optional

Link for the client to authorise/reject this agent's invitation.

Error scenarios

Error scenarios table
Scenario HTTP status Code

This user does not have a Government Gateway agent account. They need to create an Government Gateway agent account before they can use this service.

403 (Forbidden)

NOT_AN_AGENT

This agent needs to create an agent services account before they can use this service.

403 (Forbidden)

AGENT_NOT_SUBSCRIBED

The user that is signed in cannot access this authorisation request. Their details do not match the agent business that created the authorisation request.

403 (Forbidden)

NO_PERMISSION_ON_AGENCY

Missing or unsupported version found in 'Accept' header.

400 (Bad Request)

BAD_REQUEST

Missing or unsupported found in 'Accept' header.

400 (Bad Request)

BAD_REQUEST

Bad Request

400 (Bad Request)

BAD_REQUEST

Missing 'Accept' header.

406 (Not Acceptable)

ACCEPT_HEADER_INVALID

Invalid 'Accept' header.

406 (Not Acceptable)

ACCEPT_HEADER_INVALID

Bearer token is missing or not authorized.

401 (Unauthorized)

UNAUTHORIZED

INTERNAL_SERVER_ERROR

500 (Internal Server Error)

INTERNAL_SERVER_ERROR

For error scenarios that are common across all APIs, and for error formats, see our reference guide.


Close Section
/agents/{arn}/invitations

Create a new authorisation
POST

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:sent-invitations scope.

Path parameters

Path parameters table
Name Description
arn
string
required

The Making Tax Digital (MTD) platform Agent Reference Number. For format and validation of Agent Reference Number See here

For example: AARN9999999

Request headers

Request headers Table
Name Description
Accept
required

Specifies the response format and the version of the API to be used.

For example: application/vnd.hmrc.1.0+json
Authorization
required
An OAuth 2.0 Bearer Token with the write:sent-invitations scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Request

{
  "service": ["MTD-IT"],
  "clientType":"personal",
  "clientIdType": "ni",
  "clientId": "AA999999A",
  "knownFact": "AA11 1AA"
}

{
  "service": ["MTD-VAT"],
  "clientType":"business",
  "clientIdType": "vrn",
  "clientId": "101747696",
  "knownFact": "2007-05-18"
}

Response headers

Response headers Table
Name Description
Location
required

Location of the authorisation request.

For example: /agents/AARN9999999/invitations/CS5AK7O8FPC43

See also fraud prevention.

Response

HTTP status: 204 (No Content)

Error scenarios

Error scenarios table
Scenario HTTP status Code

The service requested is not supported. Check the API documentation to find which services are supported.

400 (Bad Request)

SERVICE_NOT_SUPPORTED

The client type requested is not supported. Check the API documentation to find which client types are supported.

400 (Bad Request)

CLIENT_TYPE_NOT_SUPPORTED

Client identifier must be in the correct format. Check the API documentation to find the correct format.

400 (Bad Request)

CLIENT_ID_FORMAT_INVALID

The type of client Identifier provided cannot be used with the requested service. Check the API documentation for details of the correct client identifiers to use.

400 (Bad Request)

CLIENT_ID_DOES_NOT_MATCH_SERVICE

Postcode must be in the correct format. Check the API documentation to find the correct format.

400 (Bad Request)

POSTCODE_FORMAT_INVALID

VAT registration date must be in the correct format. Check the API documentation to find the correct format.

400 (Bad Request)

VAT_REG_DATE_FORMAT_INVALID

Missing or unsupported version found in 'Accept' header.

400 (Bad Request)

BAD_REQUEST

Missing or unsupported found in 'Accept' header.

400 (Bad Request)

BAD_REQUEST

Bad Request

400 (Bad Request)

BAD_REQUEST

The details provided for this client do not match HMRC's records.

403 (Forbidden)

CLIENT_REGISTRATION_NOT_FOUND

The postcode provided does not match HMRC's record for the client.

403 (Forbidden)

POSTCODE_DOES_NOT_MATCH

The VAT registration date provided does not match HMRC's record for the client.

403 (Forbidden)

VAT_REG_DATE_DOES_NOT_MATCH

A pending invitation already exists between the agent and client for this service.

403 (Forbidden)

DUPLICATE_AUTHORISATION_REQUEST

An active relationship already exists between the agent and client for this service.

403 (Forbidden)

ALREADY_AUTHORISED

This user does not have a Government Gateway agent account. They need to create an Government Gateway agent account before they can use this service.

403 (Forbidden)

NOT_AN_AGENT

This agent needs to create an agent services account before they can use this service.

403 (Forbidden)

AGENT_NOT_SUBSCRIBED

The user that is signed in cannot access this authorisation request. Their details do not match the agent business that created the authorisation request.

403 (Forbidden)

NO_PERMISSION_ON_AGENCY

Missing 'Accept' header.

406 (Not Acceptable)

ACCEPT_HEADER_INVALID

Invalid 'Accept' header.

406 (Not Acceptable)

ACCEPT_HEADER_INVALID

Bearer token is missing or not authorized.

401 (Unauthorized)

UNAUTHORIZED

INTERNAL_SERVER_ERROR

500 (Internal Server Error)

INTERNAL_SERVER_ERROR

For error scenarios that are common across all APIs, and for error formats, see our reference guide.


Close Section
/agents/{arn}/invitations/{invitationId}

Get an invitation by id
GET

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:sent-invitations scope.

Path parameters

Path parameters table
Name Description
arn
string
required

The Making Tax Digital (MTD) platform Agent Reference Number. For format and validation of Agent Reference Number See here

For example: AARN9999999

invitationId
string
required

A unique authorisation request ID

For example: CS5AK7O8FPC43

Request headers

Request headers Table
Name Description
Accept
required

Specifies the response format and the version of the API to be used.

For example: application/vnd.hmrc.1.0+json
Authorization
required
An OAuth 2.0 Bearer Token with the read:sent-invitations scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Response

HTTP status: 200 (OK)

{
  "_links": {
    "self": {
      "href": "/agents/AARN9999999/invitations/CS5AK7O8FPC43"
    }
  },
  "created": "2019-01-21T14:27:44.620Z",
  "expiresOn": "2019-02-04T00:00:00.00",
  "arn": "AARN9999999",
  "service": ["MTD-IT"],
  "status": "Pending",
  "clientActionUrl": "https://www.tax.service.gov.uk/invitations/personal/12345678/agent-1"
}

{
  "_links": {
    "self": {
      "href": "/agents/AARN9999999/invitations/CS5AK7O8FPC43"
    }
  },
  "created": "2019-01-21T14:27:44.620Z",
  "updated": "2019-01-21T14:27:44.620Z",
  "arn": "AARN9999999",
  "service": ["MTD-VAT"],
  "status": "Accepted"
}

Response table
Name Description
_links
object
required

No description available.

self
object
required

A link to the current resource.

href
string
required

No description available.

service
array
required

What do you want the client to authorise you to do?

Limited to the following possible values:

MTD-IT - Report income or expenses through software
MTD-VAT - Report their VAT returns through software
arn
string
required

The Agent Registration Number for the calling agency

Must conform to the regular expression ^[A-Z]ARN[0-9]{7}$

created
string
required

Creation time of the request (RFC3339 / ISO8601 format)

updated
string
optional

Update time of the request (RFC3339 / ISO8601 format)

expiresOn
string
optional

Expiration time of the request (RFC3339 / ISO8601 format)

status
string
required

The current status of the invitation

Limited to the following possible values:

Pending - The invitation has been created, it has not been accepted or rejected by the client. Only the service can set this status.
Accepted - The client has accepted the invitation. Only the client can set this status.
Rejected - The client has rejected the invitation. Only the client can set this status.
Cancelled - The agency has cancelled the invitation. Only the agency can set this status.
Expired - Client did not respond to the Agent's Invitation within 21 days. Only the service can set this status.
clientActionUrl
string
optional

Link for the client to authorise/reject this agent's invitation.

Error scenarios

Error scenarios table
Scenario HTTP status Code

This user does not have a Government Gateway agent account. They need to create an Government Gateway agent account before they can use this service.

403 (Forbidden)

NOT_AN_AGENT

This agent needs to create an agent services account before they can use this service.

403 (Forbidden)

AGENT_NOT_SUBSCRIBED

The user that is signed in cannot access this authorisation request. Their details do not match the agent business that created the authorisation request.

403 (Forbidden)

NO_PERMISSION_ON_AGENCY

The authorisation request cannot be found.

404 (Not Found)

INVITATION_NOT_FOUND

Missing or unsupported version found in 'Accept' header.

400 (Bad Request)

BAD_REQUEST

Missing or unsupported found in 'Accept' header.

400 (Bad Request)

BAD_REQUEST

Bad Request

400 (Bad Request)

BAD_REQUEST

Missing 'Accept' header.

406 (Not Acceptable)

ACCEPT_HEADER_INVALID

Invalid 'Accept' header.

406 (Not Acceptable)

ACCEPT_HEADER_INVALID

Bearer token is missing or not authorized.

401 (Unauthorized)

UNAUTHORIZED

INTERNAL_SERVER_ERROR

500 (Internal Server Error)

INTERNAL_SERVER_ERROR

For error scenarios that are common across all APIs, and for error formats, see our reference guide.


Close Section
/agents/{arn}/invitations/{invitationId}

Cancel an invitation by id
DELETE

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:cancel-invitations scope.

Path parameters

Path parameters table
Name Description
arn
string
required

The Making Tax Digital (MTD) platform Agent Reference Number. For format and validation of Agent Reference Number See here

For example: AARN9999999

invitationId
string
required

A unique authorisation request ID

For example: CS5AK7O8FPC43

Request headers

Request headers Table
Name Description
Accept
required

Specifies the response format and the version of the API to be used.

For example: application/vnd.hmrc.1.0+json
Authorization
required
An OAuth 2.0 Bearer Token with the write:cancel-invitations scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Response

HTTP status: 204 (No Content)

Error scenarios

Error scenarios table
Scenario HTTP status Code

This authorisation request cannot be cancelled as the client has already responded to the request, or the request has expired.

403 (Forbidden)

INVALID_INVITATION_STATUS

This user does not have a Government Gateway agent account. They need to create an Government Gateway agent account before they can use this service.

403 (Forbidden)

NOT_AN_AGENT

This agent needs to create an agent services account before they can use this service.

403 (Forbidden)

AGENT_NOT_SUBSCRIBED

The user that is signed in cannot access this authorisation request. Their details do not match the agent business that created the authorisation request.

403 (Forbidden)

NO_PERMISSION_ON_AGENCY

The authorisation request cannot be found.

404 (Not Found)

INVITATION_NOT_FOUND

Missing or unsupported version found in 'Accept' header.

400 (Bad Request)

BAD_REQUEST

Missing or unsupported found in 'Accept' header.

400 (Bad Request)

BAD_REQUEST

Bad Request

400 (Bad Request)

BAD_REQUEST

Missing 'Accept' header.

406 (Not Acceptable)

ACCEPT_HEADER_INVALID

Invalid 'Accept' header.

406 (Not Acceptable)

ACCEPT_HEADER_INVALID

Bearer token is missing or not authorized.

401 (Unauthorized)

UNAUTHORIZED

INTERNAL_SERVER_ERROR

500 (Internal Server Error)

INTERNAL_SERVER_ERROR

For error scenarios that are common across all APIs, and for error formats, see our reference guide.


Close Section
/agents/{arn}/relationships

Get Status of a Relationship
POST

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:check-relationship scope.

Path parameters

Path parameters table
Name Description
arn
string
required

The Making Tax Digital (MTD) platform Agent Reference Number. For format and validation of Agent Reference Number See here

For example: AARN9999999

Request headers

Request headers Table
Name Description
Accept
required

Specifies the response format and the version of the API to be used.

For example: application/vnd.hmrc.1.0+json
Authorization
required
An OAuth 2.0 Bearer Token with the read:check-relationship scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Request

{
  "service": ["MTD-IT"],
  "clientIdType": "ni",
  "clientId": "AA999999A",
  "knownFact": "AA11 1AA"
}

{
  "service": ["MTD-VAT"],
  "clientIdType": "vrn",
  "clientId": "101747696",
  "knownFact": "2007-05-18"
}

Response

HTTP status: 204 (No Content)

Error scenarios

Error scenarios table
Scenario HTTP status Code

The details provided for this client do not match HMRC's records.

403 (Forbidden)

CLIENT_REGISTRATION_NOT_FOUND

The postcode provided does not match HMRC's record for the client.

403 (Forbidden)

POSTCODE_DOES_NOT_MATCH

The VAT registration date provided does not match HMRC's record for the client.

403 (Forbidden)

VAT_REG_DATE_DOES_NOT_MATCH

This user does not have a Government Gateway agent account. They need to create an Government Gateway agent account before they can use this service.

403 (Forbidden)

NOT_AN_AGENT

This agent needs to create an agent services account before they can use this service.

403 (Forbidden)

AGENT_NOT_SUBSCRIBED

The user that is signed in cannot access this authorisation request. Their details do not match the agent business that created the authorisation request.

403 (Forbidden)

NO_PERMISSION_ON_AGENCY

Relationship is inactive. Agent is not authorised to act for this client.

404 (Not Found)

RELATIONSHIP_NOT_FOUND

The service requested is not supported. Check the API documentation to find which services are supported.

400 (Bad Request)

SERVICE_NOT_SUPPORTED

Client identifier must be in the correct format. Check the API documentation to find the correct format.

400 (Bad Request)

CLIENT_ID_FORMAT_INVALID

The type of client Identifier provided cannot be used with the requested service. Check the API documentation for details of the correct client identifiers to use.

400 (Bad Request)

CLIENT_ID_DOES_NOT_MATCH_SERVICE

Postcode must be in the correct format. Check the API documentation to find the correct format.

400 (Bad Request)

POSTCODE_FORMAT_INVALID

VAT registration date must be in the correct format. Check the API documentation to find the correct format.

400 (Bad Request)

VAT_REG_DATE_FORMAT_INVALID

Missing or unsupported version found in 'Accept' header.

400 (Bad Request)

BAD_REQUEST

Missing or unsupported found in 'Accept' header.

400 (Bad Request)

BAD_REQUEST

Bad Request

400 (Bad Request)

BAD_REQUEST

Missing 'Accept' header.

406 (Not Acceptable)

ACCEPT_HEADER_INVALID

Invalid 'Accept' header.

406 (Not Acceptable)

ACCEPT_HEADER_INVALID

Bearer token is missing or not authorized.

401 (Unauthorized)

UNAUTHORIZED

INTERNAL_SERVER_ERROR

500 (Internal Server Error)

INTERNAL_SERVER_ERROR

For error scenarios that are common across all APIs, and for error formats, see our reference guide.


Close Section

Skip to main content