This version is in beta - expect some breaking changes.
Agent Authorisation API
|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|
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.
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.
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
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.
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.