Service endpoints

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

Ngā pitomutunga ratonga Service endpoints