Support centre

OAuth2 Authentication

Last Updated: Oct 16, 2017 01:54PM NZDT

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 there is no message body. The response includes a RevokedAccessToken header with the revoked token.

 

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. By default the error is returned in XML format. To receive a JSON error instead include a Content-Type header in the API call:

Content-Type: 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 your 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

Error code Error Message Description
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.
900909
The subscription to the API is inactive Happens when the API user is blocked.
900908
Resource forbidden The user invoking the API has not been granted access to the required resource.
900907
The requested API is temporarily blocked The status of the API has been changed to an inaccessible/unavailable state.
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.
900905
Incorrect Access Token Type is provided The access token type used is not supported when invoking the API.
900902
Missing Credentials No authentication information provided
900901
Invalid Credentials Invalid Authentication information provided
900900
Unclassified Authentication Failure An unspecified error has occurred
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.
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