About our APIs
Find out how Australia Post APIs work.
Request and response formats
Our APIs are based on RESTful principles. Depending on the API, request formats generally are in one
or more of five HTTP methods: GET, POST, PUT, PATCH and DELETE. The OPTIONS method is also supported
in some scenarios. Payload data is mostly sent and received in JSON format.
Access to restricted APIs
Some Australia Post APIs are restricted. When you view the documentation for these APIs, you’ll see a Request access button in the left menu.
Unrestricted APIs have a Get credentials button in the left menu. You can add apps, create credentials and try them out straight away.
Once access to a restricted API is granted by the API owner, you’ll see a Get credentials button in the left menu.
Security: authentication and authorisation
APIs connect services and transfer data. By understanding how our authentication and authorisation protocols work, you can use our APIs in the most secure way possible. That way, you ensure their integrity and avoid service disruption, data breaches or other misuse.
There are three key concepts central to understanding security in the Developer Portal:
Apps - We use apps to organise the credentials you use with our APIs. Apps act like a container for your credentials. Find out more about the role of apps in the Developer Portal.App types - Each app is assigned an app type. It describes what you're building so we can provide guidance on compatible credentials. Find out more about app types and credentials.Credential types - How an API is secured, and the type of credentials you need to access it, can vary for each API. There are four credential types supported by the Developer Portal. Find out more about the different credential types and how to use them.The role of apps in the Developer Portal
In the Developer Portal, apps play a key role in the relationship between your project and our APIs. It’s a circular relationship that breaks down into the following parts:
- Your project is made up of one or more discrete components.
- Each component is a discrete type of application. They may be desktop apps, iOS or Android apps, APIs, or another kind of service.
- You need one or more credentials to call one of our APIs from a project component.
- The API’s documentation defines the specific credential types needed to call its endpoints.
- Some credential types are only suitable for particular app types.
- You add an app on the Developer Portal, then create one or more credentials within it.
- You assign an app type to the Developer Portal app. The app type corresponds to the discrete project component that will call our API. It also supports the credential you need.
You can create as many Developer Portal apps as you need for your projects. The type of credentials you can add to your app depends on the app type you choose. Find out more about app types and credentials.App types and credentials
App types correspond to the components of the project you’re buiding. When you select an app type, it lets us know what will be calling our APIs. Each app type only works with particular credential types.
The four app types and the credentials you can use with them are:
- Machine-to-machine (M2M) applications - Non-interactive service application, such as an API or a script running on a machine.
Credential types that work with this app type: OAuth 2.0 - Client Credentials grant, API Key, Basic Auth.
- Regular web applications - Traditional web apps with a dedicated secure web server for the application. Built to run in a web browser.
Credential types that work with this app type: OAuth 2.0 - Authorisation Code grant, API Key, Basic Auth.
- Single page web applications (SPA) - Built to run in a web browser. Unlike regular web apps, SPA don’t have a dedicated secure web server for the application.
Credential types that work with this app type: OAuth 2.0 - Authorisation Code grant (PKCE), API Key, Basic Auth.
- Native applications - Built to run on specific operating systems. Examples include iOS or Android apps for mobile devices, as well as apps on non-mobile devices, such as Apple TV.
Credential types that work with this app type: OAuth 2.0 - Authorisation Code grant (PKCE), API Key, Basic Auth.
Cardinality rules
The number of credentials you can add to an app depends on the app type you choose.
For regular web apps, SPA and native apps, you can add a maximum of three credentials. These apps can contain:
- a maximum of one OAuth 2.0 Authorisation Code grant credential
- a maximum of one API Key
- a maximum of one Basic Auth credential.
In M2M apps, you can add multiple credentials. M2M apps can contain:
- multiple OAuth 2.0 Client Credentials grant credentials for APIs secured by our new identity provider, Auth0, provided each credential is for a different API
- a maximum of one API Key
- a maximum of one Basic Auth credential.
M2M apps can also contain:
- a maximum of one OAuth 2.0 Client Credentials grant credential for APIs secured by our legacy identity provider, AuthZ.
Credential types and how to use them
We use the credentials in calls to our APIs to authenticate and authorise the user or machine who made the request.
- Authentication verifies the identity of the API consumer (user or machine).
- Authorisation verifies the permissions or level of access an API consumer (user or machine) has. The permissions determine the actions, data or services the consumer is allowed to access.
API specification documents can include one or more security definitions. The four credential types supported by the Developer Portal are summarised below.
An API Key is a single unique string token that we use to authenticate a unique API consumer.
App types it’s used with
All app types. To make sure the API Key isn’t exposed in the public domain, however, we strongly recommend using API Key in M2M apps only. This minimises the risk of a security breach.
How to use it
Include the API Key in the request header when you call one of our API endpoints. Always use HTTPS so the data is encrypted in transit.
You can increase your application security by adding a restriction method. That way only authorised requests are made with your API Key.
Example
API Key (abcDef12345xyZ67jKLmnO8910) in request header: curl --request GET \
--url https://digitalapi.auspost.com.au/example-api/v1/example-endpoint \
--header 'AUTH-KEY: abcDef12345xyZ67jKLmnO8910'Rate limits
We rate-limit the number of endpoint requests that can be made from the same credentials. This helps maintain a fair and consistent service to all our API consumers.
Rate limits can be set on requests per second, minute, hour or day. If you send more requests than the limit for a given time period from the same credentials, you breach the rate limit.
If you breach an API's rate limits, all subsequent requests you make within the time period that applies return a 429 Too many requests error.
To monitor your current status, note the HTTP response headers from our endpoints:
| Response header | Description |
|---|---|
| X-RateLimit-Limit-hour | The maximum number of requests a consumer is permitted to make per hour |
| X-RateLimit-Remaining-hour | The number of requests remaining in the current rate limit window |
| X-RateLimit-Limit-day | The maximum number of requests a consumer is permitted to make per day |
| X-RateLimit-Remaining-day | The number of requests remaining in the current rate limit window |
| X-RateLimit-Limit-minute | The maximum number of requests that the consumer is permitted to make per minute |
| X-RateLimit-Remaining-minute | The number of requests remaining in the current rate limit window |
| X-RateLimit-Limit-second | The maximum number of concurrent requests that the consumer is permitted to make per second |
| X-RateLimit-Remaining-second | The number of requests remaining in the current rate limit window |
HTTP response status codes
Some of the most common response codes our APIs use are listed below.
Some of our APIs also use additional HTTP codes. Check specific documentation for each API to see which status codes it returns. View the HTTP Reference for more information on Status Code Definitions| Code | Name | Description |
|---|---|---|
| 200 | OK | Success |
| 201 | Created | Success; a new resource has been created. |
| 202 | Accepted | The request is accepted for processing, but the processing hasn't been completed. |
| 204 | No content | The server has fulfilled the request but doesn’t need to return an entity body. The response may include new or updated metainformation. |
| 400 | Bad request | The request included bad syntax or invalid request framing, or used deceptive routing. |
| 401 | Unauthorised | Valid credentials were not provided in the request. |
| 403 | Forbidden | You do not have sufficient permissions to access the resource. |
| 404 | Not found | The server didn’t find anything matching the Request URI. |
| 429 | Too many requests | You sent too many requests to the same API endpoint within a specific time period. (For more information, see rate limiting for the specific endpoint.) |
| 500 | Internal server error | The server encountered an unexpected condition that stopped it from fulfilling the request. |
| 502 | Bad gateway | The server you contacted was acting as a gateway or proxy and received an invalid response from an upstream server. |
| 503 | Service unavailable | The server is unavailable due to maintenance or temporary overload. |
| 504 | Gateway timeout | The server didn’t receive a timely response from an upstream or auxiliary server it needed to access to complete the request. |