API keys (Credentials)

API keys (or Credentials) are created when you create an app. You can also create more than one set of keys per app (using Add key), and also associate one or more APIs to your keys.

API keys are used via OAuth2.0 in order to authorize your applications connection and the use of an API. You can only use keys for APIs that are approved against those keys. You will be able to see what APIs are associated with your app’s API keys in the Dashboard by clicking on the details of a particular app.

API keys can be in one of 3 states;

Approved The API Key is approved and can be used.
Pending The API Key is pending approval and cannot be used until reviewed and approved by Bunnings.
Revoked The API Key is revoked and cannot be used.

API products listed under those API keys can also be in one of 3 states;

Enabled The API product is able to be used with those API keys.
Pending The API product is pending approval and cannot be used with those API keys until reviewed and approved by Bunnings.
Disabled The API product cannot be used with those API keys.

Approval is a join of API keys and API products. For example;

  • If the API keys are Pending, or Revoked, and one or more API products under those keys are Enabled, you will still not be able to use those API keys with those enabled API products

  • If the API keys are Approved, and an API product is Pending or Disabled, you will not be able to use those API keys with that API product

View your API keys

To view your API keys:

1

Log into sandbox-test or live

2

Under your team, click on Team Apps

3

Select your app and scroll to the Credentials section to view your API key

Generate a new API key

To generate a new key:

1

Log into sandbox-test or live

2

Under your team, click on Team Apps

3

Select your app and in the Credentials section click Add key. Select the expiry date and click Confirm.

4

To edit the API products for an API key, on the app, click Edit, select the API products for the key, then click Save

Revoke an API Key

To revoke a key:

1

Log into sandbox-test or live

2

Under your team, click on Team Apps

3

Select your app and in the Credentials section, find the API Key you wish to revoke

4

On the API Key, click Revoke

5

Click OK in the confirmation pop-up.

You can simply un-revoke (re-approve) the key again by clicking Approve on the API key.

WARNING! Once revoked any applications using that key will immediately be unable to use that key to communicate with any Bunnings API

Delete an API key

To delete a key:

1

Log into sandbox-test or live

2

Under your team, click on Team Apps

3

Select your app and in the Credentials section, find the API key you wish to delete.

4

Click the Delete on the API Key.

5

Type DELETE and click OK in the confirmation-to-delete pop-up.

WARNING! This action cannot be undone. Once deleted any applications using that key will immediately be unable to use that key to communicate with any Bunnings API. Creating new keys in test or live apps will require re-approval of your keys for any selected products.

OAuth2.0

Bunnings use OAuth2.0 for all APIs, as this is the industry standard for authorizing access and granting permission to APIs.

We have a specific token endpoint in each environment (sandbox, test and live) to get your OAuth token. Unless otherwise specified, we use the grant-type of client_credentials for our APIs.

OAuth2 token endpoint

To get an OAuth token there is an endpoint for each environment (sandbox, test and live). The token from those endpoints can only be used against APIs in that environment.

Environment endpoints
ENVIRONMENT Token URL
Sandbox https://connect.sandbox.api.bunnings.com.au/connect/token
Test https://authorisation-stg.api.bunnings.com.au/connect/token
Live https://authorisation.api.bunnings.com.au/connect/token

 

Access Tokens

Access tokens live for 1 hour (3600 seconds). Multiple access tokens can be obtained, as older tokens are not revoked when new tokens are requested.

Getting an access token

Use valid API keys to make a request to one of the environment token endpoints to get an access token. This token can only be used against approved products for those API keys in the environment you have the token for.

 

Method Endpoint Description
POST /connect/token Gets an access token
 
Request parameters

The following request parameters and values must be supplied when making a call to the OAuth endpoint to retrieve a token.

Parameter name Type Value
Content-Type Header application/x-www-form-urlencoded
client_id Body Your API Key Consumer Key
client_secret Body Your API Key Consumer Secret
grant_type Body client_credentials (unless otherwise indicated for particular APIs)
 
cURL Example
curl --location --request POST 'https://connect.sandbox.api.bunnings.com.au/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=VzpOD7hQQKQbIwW2rMv6WGo48f5sHe27' \
--data-urlencode 'client_secret=z6eqGt20RQUKAOl1' \
--data-urlencode 'grant_type=client_credentials'
Sample token response
{
    "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjI2QTIwQTQ2OTdBODUzMkZCNENBN0NGRDI2REFFMjU0RTBCQkIxNjMiLCJ0eXAiOiJKV1QiLCJ4NXQiOiJKcUlLUnBlb1V5LTB5bno5SnRyaVZPQzdzV00ifQ.eyJpc3MiOiJodHRwczovL2J1bm5pbmdzLmNvbS5hdS91YXQvIiwibmJmIjoxNjQzNTkyMzg3LCJpYXQiOjE2NDM1OTIzODcsImV4cCI6MTY0MzU5NTk4NywiYXVkIjpbIm9yZGVyaW5nLWFwaSIsImh0dHBzOi8vYnVubmluZ3MuY29tLmF1L3VhdC9yZXNvdXJjZXMiXSwic2NvcGUiOlsib3JkOm1hbmFnZW1lbnQiXSwiY2xpZW50X2lkIjoib3JkZXJfYXBpX2Zyb21fcmlza19henVyZSIsImItcmJhYyI6W3sidHlwZSI6IlIiLCJyb2wiOlsiUFA6RWNvbW1lcmNlK0Z1bGwiLCJPUkQ6T1ArU3VwZXJ2aXNvciJdfV0sImp0aSI6Ijk0OENEQTU3NDEyNEQ1ODA3MDE4NUI3NkFENzNBOUU0In0.IlXzFP0PEZjCZu4TSYJxQUGD5YDONK64Ugo9t4uWgCjsbqGU54dKlMcXatwVE2hnc87tvq44cg2rjgQRi5zBx_quOFesh3BbO649cHXMoPr2069jK-tyvSiKbPPWugX5j2G21Ixzr-agKA9YKYaSLbnLDWrpOz4k5bGilFf65nu9LArXJxtZR52RAaHrJU7y1hbbH3soTwwz1yvzmJcMZge2pljYo55JWR4Ho96pnF7khgjp0a4Gs5Ftn6GLRDN-GIdFNRM-clsdF5Pj091IdgHyjgUIb1vgYzlm9HyiSJImGNdms0cTWf6xkvfEie3rk_g3mpTZX2-GRX6f0cKEjQ",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": "ord:management"
}
Using an access token

Once an access token has been obtained use them in the Authorization header (with the value prefixed with Bearer ) of the request to the API you want to use.

cURL Example
curl --location --request GET 'https://inventory.sandbox.api.bunnings.com.au/inventory' \
--header 'x-version-api: 1.0' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjI2QTIwQTQ2OTdBODUzMkZCNENBN0NGRDI2REFFMjU0RTBCQkIxNjMiLCJ0eXAiOiJKV1QiLCJ4NXQiOiJKcUlLUnBlb1V5LTB5bno5SnRyaVZPQzdzV00ifQ' \
--data-raw ''

The API will check the token against your API keys to make sure that the call is authorized to access the API.

 

Quotas

API quotas help protect the Bunnings infrastructure from excessive API requests. API quotas block traffic once a quota limit is reached, and all further requests to the API are blocked until the quota is reset.

General Quota Limits

Quotas apply to all Bunnings APIs which will limit the number of transactions for your set of keys, and you as a developer, can make to any particular API.

Quotas apply per set of API keys and also per developer (which is the sum of traffic for all API keys for a developer) for each API product.

Inspecting quota limits

You can find the quota limits (how many transactions and the quota window) for each API product in the product documentation for each API. Be sure to look at the Quota limits as they change per API product.

You can also retrieve your current quota used and the quota limit for an API in the headers from the API response as per below.

Quota headers

 

Key Value Description
X-RateLimit-Limit integer The quota limit for the API you are using (particular to your API keys and the developer/user of the API).
X-RateLimit-Remaining integer How many requests you have remaining to the API (before the quota is reset at a particular time)

 

Quota error
{
  "fault": {
    "detail": { "errorcode": "policies.ratelimit.QuotaViolation" },
    "faultstring": "Rate limit quota violation. Quota limit  exceeded. Identifier : _default"
  }
}

Spike Arrest

Bunnings APIs are also protected against sudden excessive floods of API traffic, called spike arrests, (which are limits on transactions per second) in order to protect Bunnings infrastructure.

If you receive the following API error, inspect your application. You should also cease all traffic to the API to prevent your application being blocked by Bunnings.

Spike arrest error
{
    "type": "https://problem.api.bunnings.com.au?type=rateLimitExceeded",
    "title": "Rate limit has exceeded. Please try again after some time. ",
    "status": 429
}