Skip to main content

Takapuna office closure | Takapuna office closure. The Takapuna office is relocating to a new address so will be closed from 22 November 4pm to 26 November 4pm. From 27 November you can find the new office at: 74 Taharoto Road Smales Farm, One NZ Building, Takapuna.

Register
Search tips
For software providers

Digital service providers can connect to our gateway services through either cloud or desktop - they'll be directed to the appropriate endpoints.

Cloud-based connection endpoints

A centralised cloud location can connect through mutual TLS certificates. These need to be exchanged before connection to each environment.

On the cloud endpoint we have the ability to throttle traffic from digital service providers whose heavy usage may cause issues for other digital service providers.

Subject Description
Purpose Default endpoint to connect digital service providers to our gateway services
Client application type Cloud
Constraints Only for source locations with client side TLS certificates.
Mutual TLS We trust the certificate the digital service provider associates with the TLS connection as the client for mutual TLS connections and use it to identify the digital service provider and the web service they are using.
Minimum TLS version 1.2
Port 4046
End-user authentication and authorisation
  • The Token Auth (OAuth 2.0) process is used to authenticate end-users using their myIR logon and password and grant 3rd party software consent to access their information.
  • Requires an online user to enter their myIR logon and password to grant the application access to their Inland Revenue information.
    		•
    Organisational authentication and authorisation The M2M mechanism uses a client signed JSON Web Token (JWT) to sign messages, which lets us identify the data owner (service provider or a customer of a service provider).
    Firewalling in production
  • No IP address restrictions.
  • Access limited by certificate enrolment.
    		•
    Firewalling in non-production environments
  • Endpoints are firewalled and IP address whitelisting needed.
  • Access limited by certificate enrolment.
    		•

    Desktop connection endpoints

    A desktop server location must connect through one-way TLS.

    No client side X509 certificates are required.

    Subject Description
    Purpose

    Additional endpoint provided to facilitate connecting from desktops which might be:

    • high volumes of sources addresses
    • transient client IP addresses
    • not realistically associated with client side TLS certificates
    • not individually integrated to setup certificate trust.
    Client application type Desktop/native applications. For connecting from multiple decentralised clients.
    Constraints
  • Less scalable.
  • Subject to tighter security controls.
  • Less able to be shielded from heavy usage of the service by others.
  • OAuth2 refresh tokens will not be offered.
    		•
    Mutual TLS Server side TLS only.
    Minimum TLS version 1.2
    Port 443 (default https port)
    End-user authentication and authorisation
  • The Token Auth (OAuth 2.0) process is used to authenticate end-users using their myIR logon and password and grant 4th party software consent to access their information.
  • Requires an online user to enter their myIR logon and password to grant the application access to their Inland Revenue information.
    		•
    Firewalling in production No IP address restrictions.
    Firewalling in non-production environments Firewalled - IP whitelisting needed for gateway service endpoints.

    Endpoint URLs

    The endpoint URLs for the mock services (sandbox), test and production environments will be provided to digital service providers as part of the integration process.

    Delegated permissions

    These services let a user retrieve only the data of customers that their credential (as represented by the OAuth token) has access to.

    If an account or its data is targeted by the request parameters but the user does not have permission, an error will be returned. This access will depend on delegation permissions set up in myIR.

    Timeouts

    Our gateway services typically have a 60 second timeout configured, although this may be adjusted after testing.

    Supporting services

    Identity and access service

    Tasks

    Topics

    Other Sites

    Last updated: 28 Apr 2021
    Jump back to the top of the page