To provide a secure environment across all Apex NZ’s systems and services, the user accessing the system first needs to authenticate themselves via a username and password combination.
We use the OpenID Connect / OAuth 2 protocol and host (via the API) a series webpages that manage login and user creation process (including password reset and email workflows).
Use one of the supported flows below to obtain an access token which can be used to interact with the Apex NZ Registry API.
You will need to provide a name for your application. This will need to be unique if you are registering several. We recommend this name consist only of characters which do not need to be url encoded. In the rest of this document, this name will be referred to as client_id.
You will need to provide a redirect_uri. This is a pre-registered URL which the API will redirect your users to as part of the handshake and you will be required to provide as part of some requests.
You will receive a client_secret. This is an alphanumeric string which you must keep confidential. If you are writing a server-side application, we will enforce use of the client _secret in token exchanges, otherwise it is not used for browser-based applications and mobile apps.
Example API urls will begin with https://exampleapi.mmcnz.co.nz. Please replace this with the API url you are given.
Use the Authorisation Code flow to obtain an user access token which can be used to interact with the Apex NZ Registry API.
If your client library is capable of auto-configuration, you may be able to configure it using our configuration endpoint: https://exampleapi.mmcnz.co.nz/well-known/openid-configuration
We recommend the use of this OIDC flow for most server-based clients, browser-based clients and mobile applications.
For more information, please refer to the official specification at OpenID.net.
Redirect the user-agent to https://exampleapi.mmcnz.co.nz/connect/authorize, providing the following parameters in the query string:
It is important that both the client_id and redirect_uri match the pre-registered values obtained during registration.
The state parameter is a random string which you should keep (common practice is to store it in a cookie), and use later in step 1.3 to validate that the received authorization code was in response to the same request.
The scope parameter is used for standards compliance, and is also used in some of our more complex scenarios to select which user to generate a token for. It is not required to obtain a normal investor's authorization token and is treated as if it were "openid" if omitted.
The Apex NZ Registry API will now authenticate the end-user. This will usually involve a log-in form, with username and password. If the user successfully completes this step, flow continues to step 1.3
The Apex NZ Registry API will now redirect the user-agent to the redirect_uri provided in step 1.1
This request will contain the following query parameters:
It is important that the client validate that the state parameter matches the value provided in 1.1. This prevents a class of attacks where the client application is tricked into attempting to obtain an access token for a user other than the one currently using it.
The client application makes a request using HTTP POST to the token endpoint https://exampleapi.mmcnz.co.nz/connect/token providing the following form (application/x-www-form-urlencoded) parameters:
Browser applications and mobile applications which are not able to keep a confidential secret should not use the client_secret parameter.
A successful exchange response is a json document. The example below omits some keys you will observe in a real response, but these can be ignored.
{
token_type: Bearer
access_token: 'access token string'>
expires_in: integer
id_token: 'id token string'
}
The access_token can be used to access the API. The access token will consist only of characters which are valid in a base-64 encoded string, but is not valid base-64, and should not be decoded or otherwise transformed.
The id_token can be used if you wish to use the userinfo endpoint, but can otherwise be ignored. The id_token is also a JWT, and can be decoded using the keys found at https://exampleapi.mmcnz.co.nz/.well-known/jwks
expires_in is an integer number of seconds, after which time the access token will expire.
You can include the Bearer token with a request by including an Authorization header with your request:
Use the Client Credentials flow to obtain an full access token which can be used to interact with the Apex NZ Registry API.
Important: You must request this level of access specifically; It is not enabled unless requested.
We recommend the use of this OAuth2 flow for server-based machine to machine integrations. While the name may appear confusing at first, the name client refers to the OAuth 2 client, which is to say, your application. This flow must not be used directly from a browser or desktop-based application as it is too difficult to protect the client secret.
For the official specification please refer to: https://tools.ietf.org/html/rfc6749#section-4.4.
The client application makes a request using HTTP POST to the token endpoint https://exampleapi.mmcnz.co.nz/connect/tokenproviding the following form (application/x-www-form-urlencoded) parameters:
A successful exchange response is a json document. The example below omits some keys you will observe in a real response, but these can be ignored.
{
token_type: Bearer
access_token: 'access token string'>
expires_in: integer
id_token: 'id token string'
}
The access_token can be used to access the API. The access token will consist only of characters which are valid in a base-64 encoded string, but is not valid base-64, and should not be decoded or otherwise transformed.
The id_token can be used if you wish to use the userinfo endpoint, but can otherwise be ignored. The id_token is also a JWT, and can be decoded using the keys found at https://exampleapi.mmcnz.co.nz/.well-known/jwks
expires_in is an integer number of seconds, after which time the access token will expire.
You can include the Bearer token with a request by including an Authorization header with your request:
The AML stage is the second stage in the onboarding workflow. It includes functionality such as the CloudCheck API service, error messaging, alert notifications and email workflows.
There are a number of sub-stages and sub-workflows that can be triggered during the AML stage.
Below are a range of AML messages that can be returned from the CloudCheck API. Based on the error message we will trigger an appropriate workflow.
| Type | Description |
|---|
| Field Error | There is an issue with the data in the field. This could be caused by missing or additional characters and CloudCheck cannot perform the check unless it is correct. E.g. NZ drivers licence has to be AB123456 |
* If there is field data that does not meet CloudCheck’s validation requirements then an error message will be returned. A result PDF is not returned in this instance as the AML check has not yet been run.
| Verification Result | Pass / Partial Pass ** / Fail |
| Name | Verified / Not Verified |
| Address | Verified / Not Verified |
| Date of Birth | Verified / Not Verified |
| Watchlist ** | Verified / Match |
* A Partial Pass is treated as a PASS by default, unless otherwise specified. A Partial Pass is triggered when Name and DOB match but not the address.
** A Watchlist match is treated as a FAIL.