Scopes

Akahu's permission system and how to use it to get the data you want

As part of Akahu's dedication to privacy and the security of personal data, we use a scope system to provide only the data an app requires to function (i.e. The Principle of Least Privilege).

As an app developer, you will need to specify and give reasons for which scopes your app requires when you sign up to create an app. These scopes are enforced at the data access level, so your app will never be able to access data for which it doesn't have permission, nor ask users to grant access to data the app is not allowed to view.

For example: If your app provides account summaries on a dashboard, it has no reason to access payment or transfer scopes. If the app tried to access the /payments endpoint it would be denied.

Personal Apps

Personal apps are granted scopes to access all data, and to make TRANSFERS.

Personal apps are designed as sandboxes for developers to explore Akahu functionality. Because they are granted such extensive permissions, and due to the security and privacy risk if your access token is stolen, we recommend that you revoke access once you have finished using a personal app.

Providing Scopes for OAuth Requests

To get you up and running faster, you only need to supply Akahu with the scope for the type of OAuth request you wish to perform (enduring consent or one-off consent). Akahu will automatically add all of the additional scopes that your app is allowed to access. If you wish to request a subset of your app's available scopes, simply set the scope parameter to a space-seperated list of the scopes you desire.

Enduring Consent Scopes

Akahu provides the following scopes for requests that require enduring consent.

ENDURING_CONSENT (required)

Gives your app ongoing permission to access the user's accounts for 12 months. Supply this scope in an OAuth request to begin an enduring consent flow.

IDENTITY_EMAILS (optional)

Gives access to the user's email addresses.

IDENTITY_PHONES (optional)

Gives access to the user's phone numbers.

IDENTITY_PARTY (optional)

Gives access to the user's official name.

IDENTITY_TAX_NUMBERS (optional)

Gives access to the user's tax numbers (IRD numbers).

ACCOUNTS (optional)

Gives access to the user's connected accounts. You will only be able to view the accounts shared with you by the user. The account data visible to your app is also limited, depending on whether your app needs access to balances, metadata, or account holder details.

TRANSACTIONS (optional)

Gives access to the user's transactions. You will only be able to view transactions from accounts shared with you by the user. Further restrictions may be applied including limiting the date window viewable for your app or limiting the categories of transactions visible to your app.

STANDING_ORDERS (optional)

Gives access to the user's standing orders (also known as automatic payments). You will only be able to view standing orders that leave from accounts shared with you by the user.

TRANSFERS (optional)

Gives access to our transfer API, allowing your app to move money between a user's accounts you have been granted access to.

PAYMENTS (optional)

Gives access to our payments API, allowing your app to send money to any account number from accounts you have been granted access to.

One Off Scopes

Akahu provides the following scopes for one-off verification requests.

ONEOFF (required)

Gives your app permission to access a user's data at the time you request it. Supply this scope in an OAuth request to begin a one-off verification flow.

HOLDER (optional)

Gives access to the user's account holder information, as supplied by the chosen provider.

ADDRESS (optional)

Gives access to the user's residential and postal address, as supplied by the chosen provider.

ACCOUNT (optional)

Gives access to the user's account details, including the holder name, account number, and branch details, as supplied by the chosen provider.

Statement Scopes

Akahu provides the following scopes for to enable the retrieval of user bank statements.

STATEMENT (required)

Gives your app permission to access a user's bank statements at the time you request it. Supply this scope in an OAuth request to begin a one-off statement retrieval flow.


Did this page help you?