Scopes

Scopes define the level of access requested by your application as part of an authorisation request. Each scope grants access to a specific category of a user's financial resources (such as account details, transactions, payments, or identity information), and a user is only ever asked to share the scopes your application requests.

Each scope is enabled per-application based on the application's requirements. Your application can only request scopes that have been enabled for it, so the access you request must fall within the set of scopes configured for your application. If you need access to a scope that is not currently enabled, contact Akahu to discuss your requirements.

Akahu supports two scope formats. Legacy scopes are used by inline authorisation requests, while modern scopes are used by pushed authorisation requests (PAR) and offer finer-grained, more flexible control over the access being requested. The scope reference below lists every scope along with its legacy and modern equivalents.

Legacy scopes

Legacy scopes are Akahu's original scope format and are used by inline authorisation requests. They are supplied as a space-separated list in the scope query parameter, alongside the access request type (ENDURING_CONSENT or ONEOFF).

Legacy scopes are coarse-grained: a single legacy scope often maps to several modern scopes. For example, ACCOUNTS may grant accounts:basic, accounts:balance, and accounts:details, while TRANSACTIONS grants both transactions:credits and transactions:debits.

Because legacy scopes describe access only at a high level, their complete behaviour is determined by combining the requested scopes with the static configuration of your application. For example, the ACCOUNTS scope for one application may include access to balances, whereas the same scope for a different application may not. As a result, every user who authorises your application via an inline request is granted the same, statically-configured access.

See the scope reference for the full mapping between legacy and modern scopes.

Modern scopes

Modern scopes are used by pushed authorisation requests (PAR). They are supplied as an array of strings in the scope field of an access request.

Modern scopes are fine-grained and namespaced by resource (e.g. accounts:basic, accounts:balance, transactions:credits). This allows your application to request exactly the access it needs, rather than the broader categories described by legacy scopes.

Modern scopes are also more flexible. Rather than relying on static application configuration, behaviour that legacy scopes leave to your app's configuration (such as the transaction history period, or a payment consent's limits and payees) can be specified per request using constraints. This means the scope of access can be customised for each user.

See the scope reference for the full list of modern scopes.

Scope reference

Modern	Legacy (enduring)	Legacy (one-off)	Description
`user:basic`	`AKAHU`	`N/A`	Read basic Akahu user details such as user ID (enduring only).
`user:email`	`AKAHU`	`N/A`	Read the email address that the user used to access Akahu (enduring only).
`accounts:basic`	`ACCOUNTS`	`ACCOUNT`	Read basic information about connected accounts such as the account name, account number, account type, and attributes.
`accounts:balance`	`ACCOUNTS`	`ACCOUNT`	Read the balance of connected accounts.
`accounts:details`	`ACCOUNTS`	`ACCOUNT`	Read additional structured metadata from connected accounts (if available).
`accounts:owner`	`IDENTITY_NAMES`	`HOLDER`	Read the name of the account holder(s).
`transactions:credits`	`TRANSACTIONS`	`TRANSACTIONS`	Read credit transactions from connected accounts. Note: `transactions:credits` and `transactions:debits` must be requested together currently.
`transactions:debits`	`TRANSACTIONS`	`TRANSACTIONS`	Read debit transactions from connected accounts. Note: `transactions:credits` and `transactions:debits` must be requested together currently.
`payments`	`PAYMENTS`	`N/A`	Initiate payments from connected accounts (enduring only).
`pdf_exports`	`N/A`	`PDF_EXPORTS`	Access PDF transaction export documents from connected accounts (one-off only).
`statements`	`N/A`	`STATEMENTS`	Access PDF statement documents from connected accounts (one-off only).
`identity:name`	`IDENTITY_NAMES`	`PARTY`	Read the name registered to each customer profile of the user’s connected financial institutions.
`identity:dob`	`IDENTITY_DOB`	`N/A`	Read the date of birth registered to each customer profile of the user’s connected financial institutions.
`identity:email`	`IDENTITY_EMAIL`	`N/A`	Read the email address(es) registered to each customer profile of the user’s connected financial institutions.
`identity:phone`	`IDENTITY_PHONE`	`N/A`	Read the phone number(s) registered to each customer profile of the user’s connected financial institutions.
`identity:address`	`IDENTITY_ADDRESSES`	`ADDRESS`	Read the address(es) registered to each customer profile of the user’s connected financial institutions.
`identity:tax_number`	`IDENTITY_TAX_NUMBERS`	`N/A`	Read the tax number registered to each customer profile of the user’s connected financial institutions.