API Explorer has functions for logged in users to manage their API subscriptions and access tokens. (Note that this doesn't apply to all APIs that are listed in API Explorer, some older APIs still have access managed in different ways as described in their documentation.)
You will need to subscribe to, and receive approval for, each API individually.
An 'application' in API Explorer is a collection of APIs that a user is subscribed to. On the My Applications page you can create, rename or delete applications.
When you subscribe to an API you choose which of your applications the subscriptions should be associated with. Each application has sandbox and production API keys that can be used for all APIs subscribed to that application.
Every user of API Explorer has a pre-created application named 'DefaultApplication', and APIs are subscribed to this application unless otherwise specified.
Many users will only need the DefaultApplication, but there are some situations where it may be useful to create further applications:
- Software providers who have multiple products and want to have different API keys for each product.
- An organisation with multiple branches or teams that use one API, but each need their own separate access.
Creating and Editing Applications
To create a new application go to the My Applications page, enter the details below, and click the Add button. You can also view details of all the applications you have created, and edit or delete these.
|Name||A name that you choose to identify this application, up to 70 characters long.|
|Callback URL||This may be left blank unless you are using an API that requires 3-legged OAuth2 authentication. In that situation your application needs to have a callback URL defined for use in the customer consent and OAuth token generation process.|
|Description||A description to help you identify the purpose of your application.|
The My Subscriptions page shows the API access credentials for each of your applications and all the pending and approved API subscriptions for the application.
If you have more than one application defined you will need to select the application to show credentials and subscription details for.
The My Subscriptions page displays the Consumer Key and Consumer Secret values that are used to generate the OAuth2 bearer token that is required for production APIs at api.business.govt.nz, or sandbox environment for development and testing at sandbox.api.business.govt.nz.
Generation of API tokens is usually done with the token management API but can also be managed in the My Subscriptions screen. The Access Token field shows the OAuth token. You can enter a token validity time period in seconds and click Re-generate to create a new token, then use this in API calls.
Click the cURL button to reveal the API call that you should make to re-generate your access token. This demonstrates how to programmatically create the access token needed when you call the APIs that you are subscribed to.
If you want to have an OAuth API token that does not expire then enter -1 into the validity period field and click Re-generate. You can then use the Access Token shown on screen without ever having to call the token API to get a new valid access token.
Pending and Approved Subscriptions
When you subscribe to an API there will usually be an approval step for the API Customer Support team to verify your request and grant access. You will have to have submitted a signed API Access Agreement before access will be granted, this will be requested if you haven't already provided one.
If you have multiple applications and wish to subscribe each to the same API you will still have to go through the approval process for each subscription request.
Before access is granted the API will be shown in the My Subscriptions page with status 'PENDING', and the API's icon will be faded (highlighted in green below). You will not be able to use your API token to call the API.
Once access is granted the API subscription will be shown normally (highlighted in red below) and the API token can be used to call the API.
If you want to unsubscribe from an API you simply click on the x icon at the top-right corner of the API's details. You can resubscribe again later, though you will again need to go through the approval process.
If you wish to limit your API access to calls that only come from specific domains then you can enter these in the Allowed Domains section. This ensures that clients from a restricted domain cannot access an API even if your API token is stolen.