Skip to main content
Inland Revenue Inland Revenue
  • About us
    • About us
    • IR careers
  • News
    • Media releases
    • Updates
    • Subscribe
    • Seminars
  • Related Websites
    • Tax Technical
    • Tax Policy
    • International
  • Contact us
    • Contact us
    • Media queries
    • Tax Technical queries
    • Tax Policy queries
  • English
Register myIR login
myIR login
Individuals and families Ngā tāngata me ngā whānau
  • IRD numbers Ngā tau IRD
  • Income tax for individuals Te tāke moni whiwhi mō ngā tāngata takitahi
  • File my individual tax return Te tuku i tētahi puka tāke takitahi
  • Support for families Ngā tautoko i ngā whānau
  • KiwiSaver Poua he Oranga
  • Student loans Student loans
  • Self-employed Mahi ā-kiri
  • More... Tāpiri atu…
Business and organisations Ngā pakihi me ngā whakahaere
  • Income tax Tāke moni whiwhi mō ngā pakihi
  • Employing staff Te tuku mahi ki ngā kaimahi
  • KiwiSaver for employers Te KiwiSaver mō ngā kaituku mahi
  • Goods and services tax (GST) Tāke mō ngā rawa me ngā ratonga
  • Non-profits and charities Ngā umanga kore-huamoni me ngā umanga aroha
  • International Tāwāhi
  • More... Tāpiri atu…
Intermediaries and others Ngā takawaenga me ētahi atu
  • Tax agents Ngā māngai tāke
  • Bookkeepers Te kaikaute
  • PAYE intermediaries Ngā takawaenga PAYE
  • Payroll bureaus Ngā tari utu ā-rārangi
  • Digital service providers Ngā kaiwhakarato pūmanawa rorohiko
  • More... Tāpiri atu…
About us
  • About us
  • IR careers
News
  • Media releases
  • Updates
  • Subscribe
  • Seminars
Related Websites
  • Tax Technical
  • Tax Policy
  • International
Contact us
  • Contact us
  • Media queries
  • Tax Technical queries
  • Tax Policy queries
English
Register
myIR login
Inland Revenue
Home
Individuals and families Ngā tāngata me ngā whānau
Popular pages Ngā wharangi rongonui
Cost of Living Payment Utu mō te utu oranga IRD numbers Ngā tau IRD File my individual tax return Te tuku i tētahi puka tāke takitahi Support for families Ngā tautoko i ngā whānau Managing my tax Te whakahaere i taku tāke
More individuals and families
Familes Ngā whānau
Working for Families Working for families Child support Te tautoko tamariki Paid parental leave Te utu tiaki pēpi
Property and Trusts Ngā wharangi rongonui
Trusts and estates Ngā rōpū kaitiaki me ngā rawa tuku iho Property Ngā rawa
Individuals Ngā tāngata
Income tax for individuals Te tāke moni whiwhi mō ngā tāngata takitahi Non-residents Ngā kainoho-tāwāhi Self-employed Mahi ā-kiri Kiwisaver for individuals Kiwisaver mā te tangata takitahi Student loans Ngā pūtea taurewa ākonga Cryptoassets for individuals Ngā rawa whiti-rangi mā te tangata takitahi Unclaimed money
Situations Ngā āhuatanga
I am going overseas Kei te haere ahau ki tāwāhi I received an income tax assessment I whiwhi i ahau tētahi aromatawai tāke moni whiwhi I'm struggling to file and pay my tax
More situations
Business and organisations Ngā pakihi me ngā whakahaere
Popular pages Ngā wharangi rongonui
Covid-19 Businesses and organisations KOWHEORI-19 Ngā pakihi me ngā whakahaere File a companies income tax return - IR4 Te tuku i tētahi puka tāke moni whiwhi kamupene - IR4 Not-for-profits and charities PAYE calculator to work out salary and wage deductions Property Ngā rawa IRD numbers Ngā tau IRD
More business and organisations
Income tax Te tāke moni whiwhi
Types of business income Ngā momo moni whiwhi pakihi Tax rates for businesses Ngā pāpātanga tāke mō te pakihi Balance dates Ngā rā mutunga tau pūtea
GST Tāke hokohoko (GST)
Charging GST Te uta i te tāke hokohoko Claiming GST Te kerēme tāke hokohoko
Employing staff Te tuku mahi ki ngā kaimahi
Register as an employer Te rēhita hei kaituku mahi Paying staff Utu kaimahi Payday filing Te tāpaetanga rā utu Deductions from income Ngā tangohanga mai i ngā moni whiwhi Kiwisaver for employers Te KiwiSaver mō ngā kaituku mahi
International Tāwāhi
International tax for business Te tāke aowhānui mō ngā pakihi
Situations Ngā āhuatanga
I am starting a new business Kei te tīmata au i tētahi pakihi hou I am going to employ someone Kei te tuku mahi ahau ki tētahi tangata My business is making a loss Kei te hapa taku pakihi
More situations
Intermediaries and others Ngā takawaenga me ētahi atu
Intermediaries Ngā takawaenga
Becoming an intermediary Te tū hei takawaenga Getting authority to act Te whiwhi whakamanatanga Executive office holders Ngā kaipupuri tūnga whakahaere Linking client accounts Te honohono pūkete kiritaki Nominated person Te tangata kua whakaingoatia Tax pooling Te whakarōpū tāke Gateway services
More intermediaries and others
Tax agents Ngā māngai tāke
Agents answers Ngā Whakautu Māngai Tax agent status Te tūnga māngai tāke Extension of time arrangements Te whakaroa i ngā whakaritenga wā Managing consolidated groups Te whakahaere rōpū tōpū Income tax for individual clients of tax agents Te tāke moni whiwhi mā ngā kiritaki takitahi a ngā takawaenga News updates for tax agents
More tax agents
Digital service providers Ngā kaiwhakarato ratonga matihiko
Getting started guide About the developer portal Mō te tomokanga kaiwhakawhanake Gateway services architecture Te hanganga ratonga tomokanga Services catalogue Te putumōhio ratonga
More digital service providers
Roles Ngā tūranga
Tax agents Ngā māngai tāke Bookkeepers Ngā kaikaute PAYE intermediaries Ngā takawaenga PAYE Payroll bureaus Ngā tari ripanga utu kaimahi Other representatives Ētahi atu māngai
Search tips

Ngā pitomutunga ratonga Service endpoints

For software providers
For software providers
  • Guides and docs for developers
    • Gateway services architecture
      • Communication standards
      • Security measures for gateway services
      • Service endpoints
      • SOAP operations and message structure
      • Response status codes

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

      • Getting started guide

      Topics

      • Working with us
      • Services catalogue
      • Guides and docs for developers

      Other Sites

      • Log in to the developer portal
      • Register for the developer portal

      Moving between Inland Revenue sites

      picto--truck

      Heads up. We're taking you to our old site, where the page you asked for still lives

      Continue to old site
      Last updated: 28 Apr 2021
      Jump back to the top of the page top
      Inland Revenue Inland Revenue

      FOLLOW US

      • Facebook
      • Twitter
      • Youtube
      • LinkedIn
      • Subscribe

      CONTACT US

      • Contact Information
        • Contact us
        • Media queries
        • Tax Policy enquiries
        • Tax Technical enquiries
      • About us
      • Careers
      • International

      SHARE THIS PAGE

      • Email this page
      • Linkedin
      • Facebook
      • Twitter

      SHARE THIS PAGE

      • About the site
      • Conditions of use
      • Privacy
      • Glossary
      • Accessibility
      • Copyright
      • MyIR Help
      © Copyright 2023 Inland Revenue
      New Zealand Government
      Shielded website