Make a payment
Software providers Kaiwhakarato Pūmanawa Rorohiko

Managing myIR logon and gateway services access tokens

Find out how to access gateway services using an authorised myIR logon and create and manage access tokens using OAuth.

Managing myIR logons to enable access token usage in gateway services

To file through Inland Revenue's gateway services an organisation’s authorised representatives must have a myIR login and access rights.

The authorised representative's myIR logon must:

  • be enrolled or have delegated access to the relevant tax account 
  • have ‘file’ or ‘full account access' permissions to the relevant tax account. 

After setting up the myIR logon it can be used through gateway services to:

  • request an authorisation code, and
  • redeem the authorisation code for an OAuth access token.

If an authorised representative leaves the organisation, to continue accessing gateway services the organisation must: 

  • revoke the departing representative’s myIR logon delegated access
  • delegate organisational access to another representative’s myIR logon.

The newly assigned authorised representative must request a new authorisation code through gateway services, and then redeem the code for an OAuth access token.

If a third-party organisation acting on behalf of a client organisation uses gateway services, their authorised myIR logon must:

  • have the client organisation linked on a client list in myIR
  • have delegated access for the tax account  
  • have ‘file’ or ’full account access’ account permissions to the relevant tax account .

How to manage access tokens for gateway services

Note: a software provider application may be provided by:

  • a third-party software provider or
  • in-house by a client organisation or an organisation acting on behalf of a client organisation.

To create an authorisation token to access gateway services using Inland Revenue’s OAuth authorisation services the following steps are used for both cloud and native (desktop client) application usage.

  1. The authorised user is interacting with the software provider application. They access a protected service provided by Inland Revenue (e.g. to file a return, retrieve a balance etc.)
  2. The software provider application invokes the authorisation API to get an authorisation code, and the user’s browser is redirected to Inland Revenue's logon page.
  3. Inland Revenue prompts the authorised user to provide the myIR logon, they are authenticated.  On first use the authorised user must also confirm their consent for the software provider application to access Inland Revenue on their behalf. 
  4. Inland Revenue issues the authorisation code which is returned to the software provider application (via the browser). It has a finite time to live (TTL) of 15 minutes.
  5. The software provider application invokes Inland Revenue's token service to redeem the authorisation code for an OAuth access token. This OAuth access token has a finite time to live (TTL) of 8 hours. For cloud providers a refresh token is also provided with a finite TTL of 6 months.
  6. The software provider application can then invoke Inland Revenue’s protected services (eg to file a return) supplying the OAuth access token in the header.  The OAuth access token can be used for multiple invocations until it expires.
  7. A cloud software provider application can utilise the refresh token to request another access token for ongoing usage of the gateway service until it expires.

Supporting information

Identity and access