One-Off Identity Verification

📘
This guide is not applicable to Personal Apps. You must have a full app with identity permissions to follow this guide.

Akahu supports the one-off retrieval of identity information using an OAuth2-like flow. Unlike our Authorization OAuth2 flow, the user is not required to create an Akahu account in order to verify their identity with you. This is because accessing identity data is a one time occurrence. We do not store, log, or cache the user's login credentials, and all data retrieved through this endpoint is deleted within 30 days.

Prerequisites

Before we begin, you will need:

Your Akahu App ID Token.
Your Akahu App Secret.
Your Akahu app's Redirect URI.

The first two will be given to you when you register an app with Akahu.
Your Redirect URI must be one of those you supplied when registering your app with Akahu.

⚠️
Make sure you keep your App Secret private! Never include it in any frontend or user-accessible source code. We recommend you use environment variables to store the secret.

The Authorization Request

To begin the OAuth flow, the user must be directed to https://oauth.akahu.nz/, with several query parameters set.

Parameter	Example	Description
`response_type`	code	The type of oauth response. The only supported value is "code".
`client_id`	app_token_111111111111111111111111	Your App ID Token.
`redirect_uri`	https://example.com/auth/akahu_identity	Where to redirect the user once they have accepted or rejected the authorization. This must match one of your app's Redirect URIs.
`state`	1234567890	(Optional but required for accredited apps). An arbitrary string that will be returned with the Authorization Code. Useful to keep track of request-specific state and to prevent CSRF attacks.
`scope`	ONEOFF	The type of data you want. `ONEOFF` will begin a one-off identity verification flow.

Here is an example uri using the values above, with newlines included for readability:

https://oauth.akahu.nz?
  response_type=code&
  client_id=<<appToken>>&
  redirect_uri=https%3A%2F%2Fexample.com%2Fauth%2Fakahu_identity&
  state=1234567890&
  scope=ONEOFF

👍
By default, you only need to supply Akahu with the scope for the type of OAuth request you wish to perform. Akahu will automatically add all of the additional scopes that your app is allowed to access. If you wish to only request a subset of your app's available scopes, simply set the scope parameter to a space-separated list of the scopes you desire.

The Authorization Response

The user's authorization response is delivered to your app by redirecting the user to your app's Redirect URI, with results included in the query parameters.

A Successful Response

Once the user accepts your app's request for authorization, they will be returned to your Redirect URI with the following query parameters:

Parameter	Example	Description
`code`	id_1111111111111111111111111	An OAuth Result Code. Keep track of this for the next step.
`state`	1234567890	The state you supplied when you made the request.

An Error Response

Two types of errors can be returned:

An access denied error. The user has declined to give your app access to their statements.
A configuration error. There was something wrong with your authorization request.

Details are supplied by the error and error_description (optional) query parameters.

The error codes given are standard for OAuth implementations, for more details see this document.

Retrieving Identity Results with the OAuth Result Code

📘
At this point we diverge from the typical OAuth2 flow.

In order to get the identity data, make a GET request to the /identity/id_1111111111111111111111111 endpoint (Reference).

This request must be authorised as your app using Basic HTTP auth. See the API reference for more details.

A Successful Response

If all parameters are correct you will receive a JSON response body with the following keys:

Key	Example	Description
`success`	true	Indicates that the operation was successful.
`item`	see below	Status of the identity request.

The item returned will have the following keys.

Key	Example	Description
`_id`	id_1111111111111111111111111	The unique identifier for this identity result.
`status`	PROCESSING	Status of the identity result. This will be one of: `PROCESSING`, `COMPLETE` or `ERROR` (see Result Status for more detail).
`created_at`	2000-01-01T01:00:00.000Z	The time at which the user started the account connection process.
`updated_at`	2000-01-01T01:00:00.000Z	The time at which the result was last updated.
`expires_at`	2000-01-01T01:00:00.000Z	The time at which this identity result will be deleted from Akahu's systems. This is typically 30 days after creation.
`source`	JSON object	Details of the institution from which the data has been sourced.
`errors`	[String]	Any non-fatal errors that Akahu has encountered while retrieving the data.
`identities`	[JSON object]	Data regarding the user's name and gender. Will be included if your app has the required permissions to view it.
`addresses`	[JSON object]	Data regarding the user's addresses. Will be included if your app has the required permissions to view it.
`accounts`	[JSON object]	Data regarding the user's bank account. Will be included if your app has the required permissions to view it.

You can read about this particular object in more detail in our Identity Result docs. Otherwise you can look at an example in the API Reference.

Result Status

After a user completes the account connection process and is redirected back to your application, there is a small amount of processing that Akahu must complete before your result becomes available. While this processing is being undertaken, the result object returned by Akahu will contain no identity data and be assigned a status of PROCESSING. Because of this, you must poll the endpoint until the returned result has a status of either COMPLETE or ERROR.

The two possible lifecycles for an identity result are:

PROCESSING -> COMPLETE
PROCESSING -> ERROR

Only a COMPLETE result will contain the user's identity data.

ℹ️
Generally the result will remain with a status of PROCESSING for only a few hundred milliseconds before transitioning to COMPLETE, and will most likely have already completed by the first time you poll. Consequently, your code shouldn't need to poll for more than a total of ~5 seconds.

An Error Response

If the response success key is false, details are supplied in the message key.