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 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 (i.e. we do not offer enduring consent). 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 user's Email Address (optional).

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. The user's Email Address is optional, but highly recommended for a superior user experience.

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.io/, 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_1111111111111111111111111 Your App ID Token.
email foo@bar.com (Optional) The user's email.
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) An arbritary string that will be returned with the Authorization Code. Useful to keep track of request-specific state and to prevent CSRF attacks.
scope ACCOUNT HOLDER ADDRESS The information you are requesting. Your app must have the suitable permissions to access these scopes.

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

https://oauth.akahu.io?
  response_type=code&
  client_id=app_token_1111111111111111111111111&
  email=user%40example.com&
  redirect_uri=https%3A%2F%2Fexample.com%2Fauth%2Fakahu_identity&
  state=1234567890&
  scope=ACCOUNT%20HOLDER%20ADDRESS

Available Scopes

Akahu offers the following different scopes:

  • ADDRESS The user's addresses on file with the bank. If available, both residential and postal addresses are retrieved.
  • HOLDER The holder(s) of the account according to the bank.
  • ACCOUNT Information about the user's selected bank account, including the holder name, account number, and branch details.
  • STATEMENT The user's most recent bank statement.

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 - 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 This OAuth request's ID.
status PROCESSING Status of the OAuth request. This will be one of: PROCESSING, COMPLETE, REVIEW or ERROR.
created_at 2000-01-01T01:00:00.000Z The time at which the OAuth request was created.
updated_at 2000-01-01T01:00:00.000Z The time at which the OAuth request was last updated.
expires_at 2000-01-01T01:00:00.000Z The time at which this identity result will be securely 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 the HOLDER scope was supplied in the initial Authorization Request.
addresses [JSON object] Data regarding the user's addresses. Will be included if the ADDRESS scope was supplied in the initial Authorization Request.
accounts [JSON object] Data regarding the user's bank account. Will be included if the ACCOUNT scope was supplied in the initial Authorization Request.
links [JSON object] Link to the user's latest bank statement. Will be included if the STATEMENT scope was supplied in the initial Authorization Request.

An example response can be seen in the API Reference.

An Error Response

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