Creating Test Agents in the Sandbox

As of 25th Nov 2021, the below setup is working:

Prerequisites:

1. Setup vendor application on the Developer Hub for the Sandbox environment

2. Subscribe your vendor application to the VAT APIs you are trying to test:
   • VAT (MTD) API
   and the following:
   • Create Test User API
   • Agent Authorisation API
   • Agent Authorisation Test Support API

Steps:

1. Create an agent using the /agents Create Test User endpoint (Documentation)

   Example response:

   {
    "userId": "067962312887",
    "password": "fnjkvii3cQoa",
    "userFullName": "Taylor Mansell",
    "emailAddress": "taylor.mansell@example.com",
    "agentServicesAccountNumber": "MARN0866834",
    "agentCode": "290131684456",
    "groupIdentifier": "9697543130"
   }
   

---

2. Create a client using the /organisations Create Test User endpoint (Documentation)
   Alternatively use the Create Test User frontend

   Example response

   {
    "userId": "571213830501",
    "password": "aJ9so7mildjq",
    "userFullName": "Claude Venables",
    "emailAddress": "claude.venables@example.com",
    "organisationDetails": {
        "name": "Company UHNS5I",
        "address": {
            "line1": "16 Portobello Road",
            "line2": "Nottingham",
            "postcode": "TS5 1PA"
        }
    },
    "vrn": "966673662",
    "vatRegistrationDate": "2018-05-02"
   }
   

---

3. Grant authority for your vendor application to act on behalf of the agent (Documentation)

   Navigate to the grant authority URL

   • The scope write:sent-invitations is necessary to setup agent client relationships
   • Use your application client_id
   • Use your application redirect_uri
     
     

   https://test-api.service.hmrc.gov.uk/
     oauth/authorize?response_type=code
       &client_id=
         &scope=read:vat+write:vat+write:sent-invitations
           &redirect_uri=
   

   Login with the agent's userId and password to grant authority.

---

4. Retrieve access token with /oauth/token endpoint (Documentation)

   Example response:

   {
    "access_token": "661a961bacea332f852d397a2dafc83",
    "refresh_token": "dbebf893f08bcb18bb91311a6a952881",
    "expires_in": 14400,
    "scope": "read:vat write:sent-invitations write:vat",
    "token_type": "bearer"
   }
   

---

5. Create an agent client relationship invitation (Documentation)

   Use the Create a new authorisation endpoint

   • Use the agent's arn agentServicesAccountNumber from step 1
   • Use the client's clientId vrn and knownFact vatRegistrationDate from step 2
   • Use the agent's Authorization token access_token from step 4

   POST /agents/{arn}/invitations

   Example request for organisation clients:

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

   Example request for individual clients:

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

   Successful request will return a Location header containing the invitation id

---

6. Accept an agent client relationship invitation (Documentation)

   Use the Accept an invitation created endpoint

   PUT /agent-authorisation-test-support/invitations/{id}

   • Use the invitation id returned in step 5

---

7. Using the vat-api with an agent (Documentation)

   • Use agent's Authorization access_token returned in step 4
   • Use client's vrn from step 2