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:
- Your application directs the user to the Akahu authorization page.
- The user authenticates with Akahu.
- The user connects their financial accounts to Akahu if they haven't done so previously.
- The user chooses which accounts your application will be able to access.
- The user is redirected back to your application along with a short-lived authorization code included in the URL query parameters.
- 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.
Parameter | Example | Description |
---|---|---|
response_type | code | The type of oauth response. Currently "code" is the only supported option. |
client_id | app_token_111111111111111111111111 | Your App ID Token. |
email | [email protected] | (Optional) The user's email. |
connection | conn_1234 | (Optional) Direct the user to a specific connection from your app |
redirect_uri | https://example.com/auth/akahu | Where to redirect the user once they have accepted or rejected the access request. This must match one of your app's Redirect URIs. |
scope | ENDURING_CONSENT | The type of oauth flow to perform. ENDURING_CONSENT is all you need to supply here. |
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. |
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:
Parameter | Example | Description |
---|---|---|
code | c5bae672...88a33f1f | An Authorization Code. Keep track of this for the next step. |
state | 1234567890 | The state you supplied when you made the request. |
source | oauth | For OAuth requests, this will always be "oauth". |
event | ACCEPT | The 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:
Key | Example | Description |
---|---|---|
grant_type | authorization_code | Grant type. Only "authorization_code" is currently supported. |
code | id_1234512345123451234512345 | The Authorization Code you received earlier. |
redirect_uri | https://example.com/auth/akahu | The Redirect URI you originally supplied, for verification purposes. |
client_id | app_token_111111111111111111111111 | Your App ID Token. |
client_secret | 1a785560...c1ae44c4 | Your App Secret |
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. |
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!
Updated 3 months ago
Well done! Now view our Full API Documentation or our Quick Start Guides and start building!