Best Practices

Recommendations for building a high quality integration with Akahu

Suggest Edits

ℹ️

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 offers an additional email query parameter for the user's email address. This allows apps to streamline the OAuth flow by pre-filling the email address.

Below is an example OAuth authorization URL with an email address 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&
  [email protected]

Preventing Multiple Akahu Accounts

Akahu only allows a set of credentials to be connected to one user. If, on a subsequent OAuth flow from your app, the user accidentally enters a different email address, they will create a new Akahu account and be unable to see or connect the accounts they have shared with you.

This situation can be quite confusing for the user, who will receive an error message: "These credentials have already been connected to Akahu...". To avoid this, your app can fetch the user's current email address from the GET /me endpoint, and supply it to the OAuth flow to be pre-filled.

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 or transfers.

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 or transfers.

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 403 Forbidden.

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 5 months ago