Support centre

OAuth2 Authentication

Last Updated: Jun 28, 2018 12:10PM NZST

APIs at api.business.govt.nz use OAuth2 bearer tokens for authentication. You will need to have registered at API Explorer and have subscribed to an API. You can use the MBIE-Echo API to test the process of subscribing to an API and calling it with authentication.

 

Any API that requires end user consent to update entities, such as the Companies API or NZBN operations for updating business data, will need a three-legged OAuth token.

 

This article explains:

 

To get the Consumer Key and Consumer Secret required for token generation you need to log in to API Explorer and go to the My Subscriptions page.

 

If you need a non-expiring token this can be obtained by entering a negative number in the token period field and generating a new token, however it is best practice to programmatically generate a token with limited lifespan using the token API.

 

Generating an OAuth token

An OAuth token with one hour expiry time can be obtained using the token API at https://api.business.govt.nz/services/token. The API will return the details of a token if one is still active for the user, or will generate a new token if previous tokens have expired.

 

Request Details

 

Method: POST

Parameter Name Parameter Type Description
Authorization Header Basic access authentication

Basic <consumer_key:consumer_secret>
 
Where consumer_key:consumer_secret are base64 encoded
 
E.g. if consumer_key is MyKey and consumer_secret is MySecret:
Authorization: Basic TXlLZXk6TXlTZWNyZXQ=
grant_type Query client_credentials
 

Response Details

 

Field Name Field Format Description
scope string am_application_scope default
token_type string Bearer
expires in long Time until token expiry in seconds
token string Token to use in the Authorization header of APIs that the user is subscribed to
error string Error code (see table below)
error_description string Additional detail of error

 

Error Code HTTP Status Code Meaning
invalid_request 400 The request is malformed, a required parameter is missing or a parameter has an invalid value.
invalid_client 401 Client authentication failed.
invalid_grant 400 Invalid authorization grant, grant invalid, grant expired, or grant revoked.
unauthorized_client 400 Client is not authorized to use the grant.
unsupported_grant_type 400 Authorization grant is not supported by the Authorization Server.

 

cURL Example Request

curl -k -d "grant_type=client_credentials" -H "Authorization: Basic TXlLZXk6TXlTZWNyZXQ=" https://api.business.govt.nz/services/token

 

Example Response (success)

{
  "scope": "am_application_scope default",
  "token_type": "Bearer",
  "expires_in": 2704,
  "access_token": "493fd5985de98c53688f7ff2f8451eed"
}

 

 

Example Responses (failed requests)

 

{ "error": "invalid_client", "error_description": "Client Authentication failed." }

 

{"error":"invalid_request","error_description":"Invalid grant_type parameter value"}

 

Revoking an API token

Tokens can be revoked if necessary, e.g. if a token is compromised and you wish to prevent it from being used to access APIs.

 

Method: POST

Parameter Name Parameter Type Description
Content-Type: Header application/x-www-form-urlencoded
Authorization Header Basic access authentication

Basic <consumer_key:consumer_secret>
 
Where consumer_key:consumer_secret are base64 encoded
 
E.g. if consumer_key is MyKey and consumer_secret is MySecret:
Authorization: Basic TXlLZXk6TXlTZWNyZXQ=
token String The token to be revoked

 

Response Details

If the token is successfully revoked the response status is 200 and the response includes a RevokedAccessToken or RevokedRefreshToken header with the revoked token, there is no message body.

If the token is not found or is already revoked the response status is still 200 but no RevokedAccessToken or RevokedRefreshToken header is included.

You must ensure the appropriate header is present in the response and matches the token you provided in the request.

 

Error Code HTTP Status Code Meaning
invalid_request 400 The request is malformed, a required parameter is missing or a parameter has an invalid value.
invalid_client 401 Client authentication failed.
invalid_grant 400 Invalid authorization grant, grant invalid, grant expired, or grant revoked.
unauthorized_client 400 Client is not authorized to use the grant.

 

cURL Example Request

curl -k -d "token=493fd5985de98c53688f7ff2f8451eed" -H "Authorization: Basic TXlLZXk6TXlTZWNyZXQ=" https://api.business.govt.nz/services/revoke

 

Example Response (success)

Status 200

Headers include:

RevokedAccessToken: 493fd5985de98c53688f7ff2f8451eed

 

Example Response (failed request)

{"error":"invalid_request","error_description":"Invalid revocation request"}

 

Using an API token

To authenticate a call to an API you are subscribed to the request must include an Authorization header that includes a valid, non-expired token in the form Authorization: Bearer <token>. For example:

 

Authorization:  Bearer 493fd5985de98c53688f7ff2f8451eed

 

API Authentication Errors

Any issues with the token when calling an API will result in an error returned from the API gateway. The format for the response will be either XML or JSON:

  1. If the API call includes an Accept header then this will define the error format.
  2. If there is no Accept header then the Content-Type header will define the error format.
  3. If there is no Accept header and no Content-Type header then the format will be XML.


E.g. to specify a JSON error response include this header in the API call:

Accept: application/json

 

Example error response - XML format

<ams:fault xmlns:ams="http://wso2.org/apimanager/security">
    <ams:code>900901</ams:code>
    <ams:message>Invalid Credentials</ams:message>
    <ams:description>Access failure for API: /v2/companies-office/disqualified-directors, version: v2. Make sure you have given the correct access token</ams:description>
</ams:fault>

 

Example error response - JSON format

{
    "fault": {
        "code": 900901,
        "message": "Invalid Credentials",
        "description": "Access failure for API: /v2/companies-office/disqualified-directors, version: v2. Make sure your have given the correct access token"
    }
}

 

Error code details

HTTP Status Code Error code Error Message Description
403 900910 The access token does not allow you to access the requested resource Can not access the required resource with the provided access token. Check the valid resources that can be accessed with this token.
401 900909 The subscription to the API is inactive Happens when the API user is blocked.
403 900908 Resource forbidden The user invoking the API has not been granted access to the required resource.
401 900907 The requested API is temporarily blocked The status of the API has been changed to an inaccessible/unavailable state.
403 900906 No matching resource found in the API for the given request A resource with the name in the request can not be found in the API.
401 900905 Incorrect Access Token Type is provided The access token type used is not supported when invoking the API.
401 900902 Missing Credentials No authentication information provided
401 900901 Invalid Credentials Invalid Authentication information provided
500 900900 Unclassified Authentication Failure An unspecified error has occurred
429 900800 Message throttled out The maximum number of requests that can be made to the API within a designated time period is reached and the API is throttled for the user.
503 700700 API blocked This API has been blocked temporarily. Please try again later.



Contact us

Call us

  • 0800 624 301

06331954b2882b2fe5350819c54a3b70@mbieapi.desk-mail.com
https://cdn.desk.com/
false
desk
Loading
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
about
false
Invalid characters found
/customer/en/portal/articles/autocomplete