How to use our API portal services

The following instructions detail how to use our ATO API Portal services, from creating an account to consuming our services in production.

Step 1: register to the ATO API Portal

To register for the ATO API Portal, you need to (in this order):

• create an ATO API Portal account
• create a team
• create a team application

Create an ATO API Portal account

Creating an ATO API Portal account allows you to start the process to subscribe to application programming interfaces (APIs) and begin testing and using them in your applications.

To create an account, you need to:

• set up myGovID
• set up authorisations in RAM, which a principal authority or authorisation administrator does by
  1. logging into RAM
  2. going into the Agency access field
  3. selecting Online services for digital partners (this is a different agency permission to 'Australian Taxation Office').

Once you have set up your myGovID and authorisation in RAM, go to the ATO API Portal login page. Then follow the prompts to log in with your myGovID.

When you have successfully logged in, an account will automatically be created for you. Continue to use your myGovID to log in to your ATO API Portal account.

Create a team

A team is a way to group your applications in the ATO API Portal. You may choose to have one or multiple teams, This can be useful if your business has multiple development teams looking after different applications.

To create a team:

1. Navigate to the My teams page.
2. Select the Request new team button.
3. Complete and submit the form.
4. Your request will be reviewed by our Digital Partnership Office (DPO). They will let you know when your team has been created.
5. Once your team has been created, accept the invitation to join the team.

To accept a team invitation:

1. Navigate to the My account page.
2. Select the Invitations tab.
3. Select the Accept option against the relevant invitation. Follow the prompts to accept the invitation.

You can view all the teams you are a part of on the My teams page.

If you are not already a digital service provider (DSP), creating a Team will register you as a DSP with the DPO.

Create a team application

Once your team has been created, you can create a team application within that team. With your team application, you subscribe to the APIs you would like to use.

To create a Team application:

1. Navigate to the My teams page.
2. Select the team you would like to create the team application for.
3. Select the Team apps tab.
4. Select the Add team app button.
5. Complete the form, selecting the APIs you want to subscribe your team application to.
6. Your team application will be created automatically after you have successfully submitted the form.

Once your team application has been created, you will be able to access the consumer key (API key) for your team application. Do this by selecting the relevant team application on the Team apps page. This will be your sandbox consumer key (API key) for your team application. You will use this for developing and testing in the sandbox environment.

Step 2: complete the security questionnaire

Before getting access to production APIs, you will need to complete the Digital Service Provider Operational Framework security questionnaire and provide an assessment against the security requirements.

You can start this step at the same time as developing and testing with our APIs in the sandbox environment.

Our DPO can guide you through completing the questionnaire and understanding the requirements. If you have questions, you can contact us.

Step 3: develop and test with APIs

You will only have access to APIs in the sandbox environment until you have been approved for production access. Testing is conducted in the sandbox environment and with non-production data. 

Testing APIs in sandbox

To call APIs in the sandbox environment:

1. Select the APIs you would like to test when creating your team application
   • This enables you to use the sandbox consumer key (API key) of your team application to call these APIs.
2. Make calls to the APIs, in the sandbox environment, by following the relevant API documentation in the API catalogue. Authentication information can also be found at Client Authentication.

Calling the health check API

The health check API enables you to specifically test the authentication and authorisation patterns required to call APIs on the API gateway.

One of the requirements for production access is successfully calling the health check API in the sandbox environment. This will demonstrate your ability to successfully authenticate to the API gateway and test the authorisation scenarios relevant to you.

To call the health check API in the sandbox environment:

1. Select the sandbox health check API (along with any other APIs you would like to consume) when creating your team application
   • This enables you to use the consumer key (API key) of your team application to call the health check API.
2. Make a call to the health check API by following the health check API specification. 

Step 4: request production access

Requirements for production access

Production access for APIs will be provided when your have successfully:

• completed the Digital Service Provider Operational Framework security questionnaire and have provided an assessment against the security requirements.
• called the health check API in the sandbox environment using your team application to demonstrate your ability to authenticate to the API gateway & test the authorisation scenarios relevant to you
• completed any other testing requirements, specific to the API. These specific requirements will be outlined in the relevant API documentation.

Steps to request production access

To request access to production APIs:

1. Navigate to the View tab of the team app you would like to request production access for.
2. Select the Request production access button.
3. Complete the form, selecting the APIs you would like to subscribe your team application to for production access.
4. Your production access request will be reviewed by our DPO after you have successfully submitted the form.
5. Our DPO will confirm you have met the requirements and let know when your request for production access is approved.

You will be able to access the production consumer key (API key) for your team application once your request for production access is approved by our DPO.

To do this, select the relevant team application on the Team apps page. Your sandbox and production consumer keys (API keys) will be available in the same team application.

You can now make calls to the APIs you’ve been approved to use, in production environment, by following the relevant API documentation in the API catalogue. Authentication information can also be found at Client Authentication.