Authorizing With OAuth2

Learn how to gain permission to access a user's data

📘

This guide is not applicable to Personal Apps as they are authorized when they are created. See our Getting Started Guide to set up your Personal App.

Akahu supports the OAuth2 authorization code flow. This allows your application to request authorization from users to access their data. After a user completes this flow, your app will be granted enduring access to the user's data via our APIs.

Need a hand? Join our Slack Channel for in-person help.

Prerequisites

Before we begin, you will need:

  • Your Akahu App ID Token.
  • Your Akahu App Secret.
  • Your Akahu app's Redirect URIs (you must supply at least one of these when you register an Akahu app).

The first two will be given to you when you register an app with Akahu.

⚠️

Warning

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.

Authorization flow overview

The Akahu authorization flow consists of the following steps:

  1. Your application directs the user to the Akahu authorization page.
  2. The user authenticates with Akahu.
  3. The user connects their financial accounts to Akahu if they haven't done so previously.
  4. The user chooses which accounts your application will be able to access.
  5. The user is redirected back to your application along with a short-lived authorization code included in the URL query parameters.
  6. Your application server exchanges this authorization code with Akahu for a long-lived user access token. Your application can then use this token to make requests to the Akahu API based on the access that has been authorized by the user.

See our Example Authorization Flow for a visual reference of this process.

The Authorization Request

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

📘

Akahu does not support being embedded inside iframes.

ParameterExampleDescription
response_typecodeThe type of oauth response. Currently "code" is the only supported option.
client_idapp_token_111111111111111111111111Your App ID Token.
email[email protected](Optional) The user's email.
connectionconn_1234(Optional) Direct the user to a specific connection from your app
redirect_urihttps://example.com/auth/akahuWhere to redirect the user once they have accepted or rejected the access request. This must match one of your app's Redirect URIs.
scopeENDURING_CONSENTThe type of oauth flow to perform. ENDURING_CONSENT is all you need to supply here.
state1234567890(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.

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

https://oauth.akahu.nz?
  response_type=code&
  client_id=<<appToken>>&
  email=user%40example.com&
  redirect_uri=https%3A%2F%2Fexample.com%2Fauth%2Fakahu&
  scope=ENDURING_CONSENT&
  state=1234567890

👍

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 authorization response is delivered to your app by redirecting the user to your supplied Redirect URI, with results included in the query parameters.

A successful response

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

ParameterExampleDescription
codec5bae672...88a33f1fAn Authorization Code. Keep track of this for the next step.
state1234567890The state you supplied when you made the request.
sourceoauthFor OAuth requests, this will always be "oauth".
eventACCEPTThe type of event the user has performed. One of ACCEPT, REVOKE, UPDATE.

An error response

Two types of errors can be returned:

  • An access denied error. The user has declined to give your app access to the permissions it has requested.
  • 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.

Exchanging the Authorization Code

In order to get a User Access Token you must exchange your Authorization Code by making a POST request to the /token endpoint (Reference). This must be done within 60 seconds of receiving the Authorization Code.

The body may be a JSON string or url encoded form data, with the following keys:

KeyExampleDescription
grant_typeauthorization_codeGrant type. Only "authorization_code" is currently supported.
codeid_1234512345123451234512345The Authorization Code you received earlier.
redirect_urihttps://example.com/auth/akahuThe Redirect URI you originally supplied, for verification purposes.
client_idapp_token_111111111111111111111111Your App ID Token.
client_secret1a785560...c1ae44c4Your App Secret

A successful response

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

KeyExampleDescription
successtrueIndicates that the operation was successful.
access_token"user_token_111111111111111111111111"A User Access Token.
token_type"bearer"Will always be "bearer".
scope"IDENTITY_EMAILS ACCOUNTS ENDURING_CONSENT"The scopes granted by this User Access Token, separated by spaces.

An error response

If the response success key is false, details are supplied by the error and error_description (optional) keys.

For more information on the error codes returned, see for more details see this document.

Next steps

Now that you have a User Access Token, you can access those endpoints allowed by the permissions you requested.

Simply set the Authorization header to Bearer {User Access Token} and the X-Akahu-Id header to {App ID Token} and make a request - a good starting point is the /me endpoint, which gives you basic details of the user who authorized you.

Well done! Now view our Full API Documentation or our Quick Start Guides and start building!


What’s Next

Well done! Now view our Full API Documentation or our Quick Start Guides and start building!