Personal Apps - Advanced

By default, your personal app has broad access to your data. This is suitable for testing different API endpoints and getting to know our API, however if you plan on using our personal apps longer term, you may want to lock down the permissions assigned to your app.

All of the following settings can be found on the "Developers" page at my.akahu.nz.

Limiting account access

Perhaps the easiest permission to manage is which accounts your personal app can access. By default, your app can access all of your connected accounts when it is created. We allow you to update these, either granting access to accounts that you've just connected, or denying access to accounts that your personal app doesn't need.

Scroll down to the "Accounts" section of the page and press the "Edit" button. You can now select or deselect the accounts you want to grant access for, before pressing the "Submit" button.

Limiting permissions

You can adjust the permissions assigned to your personal app, which has the effect of allowing or disallowing access to the relevant API endpoints. For example, your personal app may not need access to your transactions, so you may want to disable that permission.

Scroll down to the "Permissions" section and press the "Edit" button. You can now select or deselect the permissions that your app requires. We recommend only giving your app access to the permissions it needs.

For security reasons, both payment and transfer permissions are disabled by default. These need to be manually enabled if you want to use these features from your personal app.

Save your permissions by pressing the "Submit" button.

Limiting IP addresses

By default we allow any IP address to use your Personal App credentials, however if your personal app will be running from only a few machines, you can restrict the IP addresses to prevent misuse of your access token.

We use CIDR notation to specify IP addresses. For help turning your IP (or IP ranges) into this format, you can use this tool. We currently only support IPv4 address ranges for this setting.

Scroll down to the "IP Address Ranges" section and press the "Edit" button. You can now add, remove, or edit the IP ranges allowed to access your app. Save your changes by pressing the "Submit" button.

What to do if you think your credentials have been exposed

Akahu makes it easy to rotate your app credentials in the event of exposure. We recommend you do this as soon as you realise that your token may have become public.

Scroll down to the "Danger Zone" section and press the "Regenerate" button next to "Regenerate User Access Token". Confirm that you want to do this, then take note of the new User Access Token. This token should now be used in place of the exposed token.

📘

Changes take effect immediately. Usage of an old token will result in a 401 Unauthorized response.

How to delete your app

Scroll down to the "Danger Zone" section and press the "Delete" button next to "Delete Personal App". Confirm that you want to do this, and your app will be deleted and all access revoked. Usage of your Personal App credentials will now result in a 401 Unauthorized response.

📘

Changes take effect immediately. Usage of your token will result in a 403 Forbidden response.

What is two-factor authentication (2FA) and why do I need it?

Two-factor authentication (also referred to as multi-factor authentication) is an additional layer of security on top of your normal login.

When it is enabled, in addition to clicking a link from your email (or entering the email code), you will be asked to enter a 6-digit code generated by an authenticator app on your mobile device in order to log in. This makes your account more secure, because anyone trying to log in would need to have access to your mobile device in addition to your email inbox.

Akahu requires you to set up two-factor authentication before allowing you to create or manage your personal app.
This is because your personal app has a high level of access to your financial accounts (including being able to trigger payments from your bank accounts).
Even if you have locked down your personal app permissions, an attacker who can log into my.akahu.nz can relax these restrictions, giving them full access.

Why do I need to verify my identity?

Before setting up two-factor authentication, Akahu requires you to verify your identity.
This allows us to make sure that personal apps are not abused or used for malicious purposes.

Akahu uses Cloudcheck to do this verification, making it quick and easy for NZ users to verify themselves.
If you cannot verify your identity using Cloudcheck, please contact us with proof of your identity (preferably a passport or drivers license).