Support centre

Three-Legged OAuth2 authentication

Last Updated: Jul 24, 2019 03:49PM NZST

Some APIs at require an end user to provide consent for the API to access a system on their behalf, including the Companies API and some operations for the NZBN API. This requires the use of a three-legged OAuth2 token for authentication and authorisation, which is a more complex integration than the standard  two-legged authentication.


This article explains:

For details on how to revoke tokens and use tokens in API calls see our other support article on OAuth2 use for MBIE APIs.


Application registration

You will need to have registered at API Explorer and have subscribed to an API that requires end user authorisation, such as Companies, NZBN, or PPSR APIs.


You also need to provide a callback URL to receive a code during the token generation process. This URL needs to be entered for the application that you have subscribed with.


Note: The name of the application that you subscribe with will be presented to end users during the authorisation process.



Generating a Three-Legged Token

The sequence for obtaining consent from a user for your software to act on their behalf is described below. The same process is used for test and production environments, only differing in the ID you use during the process:


1. Software initiates authorisation flow


Your software invites a user to allow your product to access and update their information (e.g. “Would you like to be able to use [PRODUCT NAME] to maintain your company information for you?”).


2. Software directs user to log in


If the user agrees, your software sends them to the OAuth Authorize page




REQUIRED. Value MUST be set to "code".


REQUIRED. The Consumer Key for the application you have subscribed with. You can get this from the My Subscriptions screen.

During your development and testing phase you should use your Sandbox Consumer Key to generate tokens for use in the sandbox test environment.


REQUIRED. The callback URI for the application, as set in the My Applications screen.


REQUIRED. Set to the scope required by the API that the token is to be used with.
For NZBN and Companies APIs use NZBNCO:manage
For PPSR API use PPSR:manage


RECOMMENDED. An opaque value used to maintain state between the request and callback. The authorization server includes this value when redirecting back to the application.




3. Login page presented


The API Authorisation Server redirects the user’s browser to a login page as used on the system that the API is accessing (e.g. a RealMe login for the Companies Register).


This page may not be presented if the user has already logged in recently. See Logging out a user for more details.


Note: The login page is determined by the scope and type of key (sandbox/production) used in the previous request. Some systems may use different logins for test and production environments (e.g. the Companies Register test environment uses the 'ITE' test RealMe, while the PPSR test environment uses production RealMe logins). 


4.User gives consent


The API Authorisation Server presents a request for the user to confirm that your product has consent to access their resources. Note that the name of your subscribed application is presented to the user.



5. Authorisation Server sends your software the result of consent


If the user approves access then the API Authorisation Server sends an authorisation code, and the state value if included in the request, back to the application’s callback URL. E.g.


If the user denies access the Authorisation Server will send e.g. access_denied&error_description=User%20denied%20access&state=b4fa9af1-a29d-4093


6. Software gets OAuth token


Your software retrieves a three-legged OAuth token by calling the token API at using these parameters:

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=
code Query Code as returned in step 5
grant_type Query authorization_code
redirect_uri Query The callback URI for the application that the API subscription is under.




cURL request:

curl "" --user "ABCDE12345XYZ789:TestPassword" -X POST


Example response:

  "scope": "NZBNCO:manage",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "abcdef67f14b793880bc87633198765",
  "access_token": "daf1c973029cd6cfb5debfaca40764d5"


Response Parameter Name Description
Expires_in Time to expiry for token (seconds). The access token has a one hour expiry time. The refresh token may be used to generate a new access token after that time, without requiring the end user to go through the consent process again.
Access_token Authorization that needs to be passed in the http request header for the API call.
Refresh_token This token can be used to get a new token once an access_token expires. Refresh tokens are valid for 14 months. If the refresh token is not used to generate new tokens in that time then the end user will need to provide consent again.


7. Software stores token


Your software stores the access and refresh tokens for use in future API requests that require that user’s consent.  The access token is passed in the Authorisation header of an API call.


Using the Refresh Token

The refresh token can be used to generate a new access token after one has expired, without requiring the end user to go through the consent process again.


Call the token API at using these parameters:

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=
refresh_token Query The refresh_token value as returned from the previous call to the token API.
grant_type Query refresh_token





cURL request:

curl "" --user "ABCDE12345XYZ789:TestPassword" -X POST

The response is the same as the call to the token API shown in step 6 above.


Logging out a user

When a user logs in to RealMe in step 3 they will remain logged in for a 20 minute session. If your software again directs them to the authorise page during that session, as in step 2,  then they won't be sent to the login and consent page again as they are still logged in.


A user can be logged out, which may be useful if they need to log in again with a different account. Use this page to log the user out:{logout_page}&relyingParty={client_id}


logout_page is the page to return the user to and client_id is the value used when logging them in.

Contact us

Call us

  • 0800 624 301
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
Invalid characters found