Make a payment
Software providers Kaiwhakarato Pūmanawa Rorohiko

Endpoints

Software providers can connect to our gateway services through two types of endpoints – cloud and desktop.

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 controls to shield software providers from issues caused by heavy usage from other providers.

Purpose Default end point to connect software 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 software provider associates with the TLS connection as the client for mutual TLS connections and use it to identify the software provider with the web service consumer identification.
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 IR user ID and password and grant 3rd party software consent to access their information.
  • Requires an online user to enter their myIR user ID and password to grant the application access to their IR information.
Firewalling in production
  • No IP address restrictions.
  • Access limited by certificate enrolment.
Firewalling in non-production environments
  • OAuth 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.

Purpose Additional end point 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 IR user ID and password and grant 4rd party software consent to access their information.
  • Requires an online user to enter their myIR user ID anad password to grant the application access to their IR information.
Firewalling in production No IP address restrictions.
Firewalling in non-production environments Firewalled - IP whitelisting needed for both OAuth and gateway service endpoints.

Identity and access service

End point URLs

The end point URLs for the mock services, test and production environments will be provided to software 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.