Using this API product
Description
You can use the DSG health check API to check the current operational status of the ATO Digital Services Gateway to determine its readiness to accept traffic.
API Risk Rating
1 - No risk
For more information, see API risk rating.
Authentication
See: M2M client authentication.
Authorisation
For authorisation test scenarios, see: Authorisation test scenarios.
Scopes
ato.healthcheck.*.*
Rate Limit
Appropriate rate limits are applied to prevent misuse or overuse of the API.
API List
Health Check API
Overview
You can use this API to test you are able to successfully connect to the DSG.
This API has the following endpoints:
- GET {serverUrl}/healthcheck/v1/heartbeat Use this endpoint to make a request to check your connection to the DSG
- GET {serverUrl}/healthcheck/v1/clients/ABN/{abn_business}/individuals/TFN/{tfn_individual}/heartbeat Use this endpoint to make an authorized request to check your connection to the DSG using the payer ABN in sandbox environment
- GET {serverUrl}/healthcheck/v1/clients/WPN/{wpn_business}/individuals/TFN/{tfn_individual}/heartbeat Use this endpoint to make an authorized request to check your connection to the DSG using the payer WPN in sandbox environment
- GET {serverUrl}/healthcheck/v1/ Use this endpoint to give the current version and status of the healthcheck API
- GET {serverUrl}/healthcheck/v1/specs/yaml Use this endpoint to view the Healthcheck Open API specification in YAML format
- GET {serverUrl}/healthcheck/v1/specs/spec.yaml Use this endpoint to download the Healthcheck Open API specification in YAML format
Note: {serverUrl}/healthcheck/v1/heartbeat endpoint will check your connection to the DSG via authentication but not authorization. The following endpoints {serverUrl}/healthcheck/v1/clients/ABN/{abn_business}/individuals/TFN/{tfn_individual}/heartbeat and {serverUrl}/healthcheck/v1/clients/WPN/{wpn_business}/individuals/TFN/{tfn_individual}/heartbeat will check your connection to the DSG via authentication and authorization.
For more in-depth information refer to the endpoint paths in the specifications below around the use of the endpoints and desired input path and query parameters.
API specification
Release notes
Release notes
Security scopes updated 28 October, 2022.
Security scope associated with this API has changed.
The new scope is: ato.healthcheck.*.*
Please refer to M2M Client Authentication on how to provide the scopes while making a call to this API.
Version 1.0.110 released on 12th September, 2022 (latest).
The endpoints have changed. You need to provide the payer and payee identifiers in the URL before sending a request in order to test authorization scenarios and connection to DSG. This should be carried out for testing purposes before moving onto the use of other APIs on the platform. Original endpoints have also been kept in the API for use in non-sandbox environments and work the same way they did previously.
Changes to Healthcheck API –
- Added two new endpoints to healthcheck to allow the testing of authorization in the Healthcheck API
Following are the new endpoint URLs –
- GET {serverUrl}/healthcheck/v1/clients/ABN/{abn_business}/individuals/TFN/{tfn_individual}/heartbeat
- GET {serverUrl}/healthcheck/v1/clients/WPN/{wpn_business}/individuals/TFN/{tfn_individual}/heartbeat
Note: The existing GET {serverUrl}/healthcheck/v1/heartbeat endpoint will check your connection to DSG via authentication only and not authorization. If you want to test authentication and authorization flows for the Healthcheck API you will need to use the above endpoints in sandbox testing environments.
We have introduced a query parameter – context. The context parameter specifies the ABN of the intermediary, the tax agent number (TAN), or registered agent number (RAN)
- When a payer is submitting a request for its newly joined payee: context not required
- When an intermediary that is not an agent is acting on behalf of the payer submitting a request: context=”ABN={abn_intermediary}”; note the intermediary doesn’t have a TAN or a RAN as it is not an agent
- When an agent is acting on behalf of the payer submitting a request, TAN or RAN of the intermediary has to be provided in the context, for example, context=”TAN={TAN}” or context=”RAN={RAN}”
Refer to the open API specification for more detail.
We have provided a number of healthcheck and authorization test scenarios that you can use to test the use of the Healthcheck API in your software in the sandbox environments. See authorisation test scenarios.