Authorising With OAuth2

📘

This guide is applicable to enduring account connectivity (both data and payments) and one-off account connectivity (data only). One-off payments use a separate authorisation flow.

This guide is not applicable to Personal Apps. See our Getting Started Guide to set up your Personal App.

Akahu uses the OAuth2 authorization code flow to facilitate your application's request to access a user's financial resources.

The scope of access requested can include read operations (data access), write operations (payments), or a combination of both. After a user completes the authorisation flow, your application will be granted the ability to access the user's financial resources, according to the scopes they have authorised.

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

Prerequisites

To implement the end-to-end authorisation flow, you will need:

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

The first two will be given to you when you register your application with Akahu.

⚠️

Sensitive value: Keep your App Secret private! Never include it in any frontend or user-accessible source code. Always handle sensitive values with care and follow secret management best practices.

Authorisation flow overview

The Akahu authorisation flow consists of the following steps:

1. Your application constructs an authorisation request.
2. Your application directs the user to Akahu's authorisation URL.
3. The user authenticates with Akahu.
4. The user connects their financial accounts and 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 authorised by the user.

The authorisation request

The authorisation request configures Akahu's authorisation flow for your specific application and the type of access you wish to request from the user.

Akahu supports two methods for constructing an authorisation request. An inline request is built as an authorisation URL and is the simplest option for read-only access. A Pushed Authorisation Request (PAR) is submitted server-to-server and returns an authorisation_url; it allows fine-grained, per-user control over the access requested and is recommended for payments and other advanced use cases.

To learn how to construct an authorisation request using either method, see Anatomy of an authorisation request. The Inline authorisation request section includes a simple example to get you started.

Once you have your authorisation URL, navigate to this URL in the browser to begin the authorisation flow.

The authorisation response

The authorisation response is delivered to your application 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 authorisation, they will be returned to your supplied Redirect URI with the following query parameters:

The event parameter distinguishes what the user did during the flow. ACCEPT indicates a new authorisation. UPDATE indicates that an existing user modified their authorisation (e.g. adding or removing accounts), and REVOKE indicates that an existing user revoked your application's access. Only the ACCEPT and UPDATE events return a code to exchange.

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 authorisation 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. After this window the code expires and is rejected, and the user will need to complete the authorisation flow again to obtain a new one.

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

A successful response

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

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 this document.

Next steps

Now that you have a User Access Token, you can use this token to authenticate requests to our API.

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 Akahu user who authorised the access.

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