Guides

Best Practices

Recommendations for building a high quality integration with Akahu

ℹ️

This reference is intended for developers using Akahu's enduring account connectivity. Information provided may not be relevant for those using one-off account connectivity.

Webhooks

Webhooks are the best way to ensure that your application is showing users the most up-to-date view of their connected account data and payments. Some important webhooks that your application should subscribe to are:

  • TOKEN:DELETE: be notified when a user revokes your access. This is particularly important because a user may revoke your access via my.akahu.nz, which is otherwise difficult for your application to detect.
  • ACCOUNT:UPDATE: know immediately when there is up-to-date account balance data available and detect changes to account status caused by Akahu losing access to the account.
  • PAYMENT:UPDATE: track the progress of payments in real-time and give speedy feedback to your users.

Streamlining onboarding

The Akahu OAuth flow accepts a login_hint parameter containing the user's email address or Akahu user ID. Akahu uses it to prefill the user's sign in, which saves them a step.

Below is an example OAuth authorization URL with a login hint specified (newlines inserted for readability):

https://oauth.akahu.nz?
  client_id=app_token_1111111111111111111111111&
  response_type=code&
  redirect_uri=https://example.com&
  scope=ENDURING_CONSENT&
  login_hint=demo%40example.com

The same parameter is available with a pushed authorisation request in the request body.

Preventing multiple Akahu accounts

Each connected account belongs to a single Akahu user. If, on a subsequent OAuth flow from your app, the user signs in to Akahu with a different email address, they will create a new Akahu account and won't see the accounts they previously shared with you.

For classic connections, a set of login credentials can only be connected to one Akahu user. If the user tries to connect them again from the new Akahu account, they will receive an error message: "These credentials have already been connected to Akahu...".

A common cause of this is an app passing the email address from its own records as the login_hint on every OAuth flow. If the user signed in to Akahu with a different email address the first time, the wrong address gets prefilled.

To avoid this:

  1. After a token exchange, call GET /me with the new access token and store the Akahu user ID (_id) against the user in your app. If a different Akahu user ID is already stored, see Handling a change of Akahu user.
  2. On later OAuth flows for that user, pass the stored user ID as the login_hint.

Your own record of the user's email address is still a good login_hint for their first OAuth flow, before you have an Akahu user ID for them.

Handling a change of Akahu user

login_hint only prefills the sign in. The user can still sign in to Akahu as a different user, and your app will then receive an access token for that user.

For example, a user first connects their bank accounts after signing in to Akahu with email address A, and your app receives an access token for that Akahu user. Later they return to the OAuth flow, sign in with email address B and connect another account. Your app receives a second access token, this time for the Akahu user with email address B.

Apps often discard the token for user A at this point and keep the new one. Akahu has no way of knowing the old connection is no longer wanted, so the token for user A stays active. If your app is billed per active user, you will continue to be charged for it.

There are two ways to handle this:

  • Allow more than one Akahu user, and their access tokens, to be linked to each user in your app.
  • Revoke the old access token when a different Akahu user is connected. This is the simpler option.

To revoke the old token:

  1. After each token exchange, call GET /me with the new access token to get the Akahu user ID.
  2. If the user already has an Akahu connection in your app, compare this ID with the one you stored.
  3. If the IDs differ, revoke the old access token with DELETE /token before discarding it.
  4. Store the new access token and Akahu user ID, replacing the previous ones.

The stored user ID is then the one you pass as the login_hint on the user's next OAuth flow.

Hosting the OAuth flow on mobile

AppAuth (recommended)

We recommend that developers use the AppAuth pattern to ensure that your users have a reliable, consistent authorisation experience.

This method involves your app opening Akahu’s OAuth flow using the user’s default mobile web browser. Once authorisation is complete, Akahu will navigate the user back to your app using a redirect URI (provided by you) that either uses a custom scheme such as app-name:// or an https:// URI that is registered to your mobile app using App Links (Android) / Universal Links (iOS).

Embedded browsers

If you prefer to embed the Akahu OAuth flow in your mobile app using an embedded browser rather than the recommended AppAuth pattern, your app should use the following embedded browser options:

Android

On Android, Akahu OAuth should be hosted using Android Custom Tabs.

Akahu does not officially support being hosted in an Android Webview for security reasons. Future support cannot be guaranteed for Webview based authorisation.

iOS

On iOS, Akahu OAuth should be hosted using SFSafariViewController or ASWebAuthenticationSession.

Akahu does not officially support being hosted in a WKWebView for security reasons. Future support cannot be guaranteed for WKWebView based authorisation.

Hosting the OAuth flow in an iframe

Akahu's OAuth flow must not be hosted in an iframe due to security restrictions implemented by banks for official open banking connections.

What happens when credentials change?

Akahu logs into providers in order to retrieve information or take actions. If the user changes their username, password, or other authentication information, Akahu may no longer be able to log in.
In this case Akahu switches the status attribute of affected accounts to INACTIVE. When an account is INACTIVE it will no longer receive periodic data refreshes, and can no longer be used to make payments.

If you see user accounts that are in an INACTIVE state there are two possible remedies:

  1. Prompt the user to complete the OAuth flow again. At the point where they select which accounts to share, they will be able to reconnect any INACTIVE accounts.
  2. Direct the user to my.akahu.nz. Here they can sign in and reconnect those accounts that have become INACTIVE.

Once the accounts have been reconnected their status will switch back to ACTIVE. At this point they will receive updates and can once again be used to make payments.

Deleting users and revoking access

When your app deletes a user

When you delete a user in your app, be sure to revoke the User Access Token using the DELETE /token endpoint. This ensures that the token can no longer be used to access user data.

⚠

This is a requirement of our App Accreditation Process, and therefore MUST be implemented before your app will be allowed to use Akahu outside of the sandbox.

If your app is billed per-active-user then this will also prevent you from being charged for users who no longer use your app.

Allowing users to revoke access

Akahu’s purpose is to give people control of their data. To ensure this, we require that apps allow their users to revoke account access from within the app itself. This can be done using the DELETE /token endpoint.

⚠

This is a requirement of our App Accreditation Process, and therefore MUST be implemented before your app will be allowed to use Akahu outside of the sandbox.

A user may also choose to revoke access via my.akahu.nz.

When a user revokes your app

If a user revokes access to your app, two things will happen:

  1. If your app is subscribed to webhooks for this user, you will receive a TOKEN DELETE webhook.
  2. Any requests for user data will return a response with the HTTP status code 401 Unauthorized.

In either of these situations you can safely discard the Akahu User Access Token corresponding with this user (you don't need to call the DELETE /token endpoint, since the token has already been revoked).
In accordance with New Zealand’s Privacy Act 2020, you must also delete any user data that has been exchanged via Akahu and is no longer reasonably required.

⚠

This is a requirement of our App Accreditation Process, and therefore MUST be implemented before your app will be allowed to use Akahu outside of the sandbox.

You may also wish to update the state in your app, explaining to the users that their accounts are no longer connected and inviting them to reconnect accounts if they wish to do so.

Updated 6 days ago

Did this page help you?