Akahu Auth API
The Auth API from Akahu — 2 operation(s) for auth.
Operations 3
Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay
The Auth API from Akahu — 2 operation(s) for auth.
Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/akahu:akahu-auth-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Akahu Enduring Auth API
description: This API is the primary way for apps to interact with a user's data.
version: 1.0.0
servers:
- url: https://api.akahu.io/v1
tags:
- name: Auth
paths:
/par:
post:
summary: Create a pushed authorisation request
tags:
- Auth
deprecated: false
security: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
client_id:
$ref: '#/components/schemas/AppTokenId'
client_secret:
type: string
description: Your App Secret
login_hint:
$ref: '#/components/schemas/EnduringLoginHint'
redirect_uri:
type: string
format: uri
description: The redirect URI to use when redirecting the user back to your application.
redirect_mode:
$ref: '#/components/schemas/OAuthRedirectMode'
response_type:
$ref: '#/components/schemas/OAuthResponseType'
state:
type: string
description: Any request state that should be passed back to your application when redirecting.
correlation_id:
type: string
request:
$ref: '#/components/schemas/AccessRequest'
required:
- client_id
- client_secret
- redirect_uri
- response_type
- request
example:
client_id: app_token_123
client_secret: supersecret
request:
type: enduring_access
scope:
- accounts:basic
- accounts:balance
- accounts:owner
- identity:name
connections:
- anz
- asb
- bnz
- westpac
- kiwibank
- nzhl
login_hint: user_123
redirect_uri: https://example.com/callback
response_type: code
state: my_encrypted_state
application/x-www-form-urlencoded:
schema:
type: object
properties:
client_id:
$ref: '#/components/schemas/AppTokenId'
client_secret:
type: string
description: Your App Secret
login_hint:
$ref: '#/components/schemas/EnduringLoginHint'
redirect_uri:
type: string
format: uri
description: The redirect URI to use when redirecting the user back to your application.
redirect_mode:
$ref: '#/components/schemas/OAuthRedirectMode'
response_type:
$ref: '#/components/schemas/OAuthResponseType'
state:
type: string
description: Any request state that should be passed back to your application when redirecting.
correlation_id:
type: string
request:
$ref: '#/components/schemas/AccessRequest'
required:
- client_id
- client_secret
- redirect_uri
- response_type
- request
example: client_id=app_token_123&client_secret=supersecret&request=%7B%22type%22%3A%22enduring_access%22%2C%22scope%22%3A%5B%22accounts%3Abasic%22%2C%22accounts%3Abalance%22%2C%22accounts%3Aowner%22%2C%22identity%3Aname%22%5D%2C%22connections%22%3A%5B%22anz%22%2C%22asb%22%2C%22bnz%22%2C%22westpac%22%2C%22kiwibank%22%2C%22nzhl%22%5D%7D&login_hint=user_123&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&response_type=code&state=my_encrypted_state
responses:
'201':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/AuthorisationRequestSuccessResponse'
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAuthorisationRequestInvalidRequestResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthUnauthorizedResponse'
'415':
description: Unsupported media type
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthInternalServerErrorResponse'
operationId: postPar
x-operation-id-source: derived
/token:
post:
tags:
- Auth
summary: Exchange an Authorization Code
security: []
description: 'This endpoint is the final step in our 📖 OAuth Authentication Flow.
Use this endpoint to exchange an **Authorization Code** for a **User Access Token**, which can be used to access the rest of this API.
To ensure that your application does not retain unnecessary access to user data, revoke this access token in the event that is no longer required (e.g. the user deletes their account).
**Endpoint not applicable for Personal Apps**. See our 📚 Getting started guide to set up your Personal App.
> 📘
>
> **OAuth2 Error Responses**
>
> In keeping with the OAuth2 specification, error responses from this endpoint contain an error in the `error` field, rather than the `message` field used by other Akahu endpoints.
For more details see:
- 📚 OAuth Authentication Flow.
- 📖 Auth scopes
- 📖 Token webhooks
- 📚 Accessing transactional data guide
- 📚 Accessing account data guide'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- grant_type
- code
- redirect_uri
- client_id
- client_secret
properties:
grant_type:
type: string
description: Must always be `authorization_code`
example: authorization_code
code:
type: string
description: The code to be exchanged for a **User Access Token**, received upon the user's completion of the authorization redirect flow.
example: code
redirect_uri:
type: string
description: Same `redirect_uri` you specified to start the OAuth flow to receive an exchange code.
example: http://localhost:3000/redirect
client_id:
type: string
description: Your Akahu **App ID Token**
example: '{{app_auth}}'
client_secret:
type: string
description: Your Akahu **App Secret**
example: '{{appSecret}}'
responses:
'200':
description: Successful response.
content:
application/json:
schema:
description: Granted token details
$ref: '#/components/schemas/Token'
'400':
description: Your request was malformed or otherwise unacceptable. The `error` key in the response will be on one of the standard OAuth error codes.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
error:
type: string
examples:
invalid_client:
summary: Invalid Client.
description: The `client_id` is invalid.
value:
success: false
error: invalid_client
invalid_grant:
summary: Invalid Grant.
description: There is something wrong with this OAuth request. Ensure you're following the specification.
value:
success: false
error: invalid_grant
expired_grant:
summary: Expired Grant.
description: This code has expired.
value:
success: false
error: expired_grant
invalid Request:
summary: Invalid Request.
description: This request is invalid. Ensure you're following the specification.
value:
success: false
error: invalid Request
unsupported_grant_type:
summary: Unsupported Grant Type
description: The grant type must always be `authorization_code`
value:
success: false
error: unsupported_grant_type
'500':
description: Internal Error
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
error:
type: string
example:
success: false
error: server_error
operationId: postToken
x-operation-id-source: derived
delete:
tags:
- Auth
summary: Revoke a token
security:
- user_token: []
description: 'Revokes the **User Access Token** that is included in the `Authorization` header of the request.
Revoking a User Access Token will remove your access to **all** of a user''s connected account data including transactions.
> ℹ️
>
> Users can re-authorize your application''s access to their accounts via the 📚 authorisation flow.'
parameters:
- $ref: '#/components/parameters/xAkahuId'
responses:
'200':
description: Successful response.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'500':
$ref: '#/components/responses/500'
operationId: deleteToken
x-operation-id-source: derived
components:
schemas:
AccountId:
type: string
format: cuid
pattern: ^acc_[a-z0-9]{25,27}$
example: acc_c01234567890123456789012345
description: A unique identifier for the account in the Akahu system. It is always prefixed by `acc_` so that you can tell that it belongs to an account.
EnduringAccessRequest:
type: object
properties:
type:
type: string
enum:
- enduring_access
connections:
$ref: '#/components/schemas/ConnectionsArray'
scope:
type: array
items:
$ref: '#/components/schemas/EnduringAccessScope'
description: 'Which scopes your application is requesting access for this request.
Defaults to all scopes enabled for your application.
If the user already has a previous authorisation with less or more scopes, this will not trigger a replacement.'
constraints:
$ref: '#/components/schemas/EnduringAccessConstraints'
required:
- type
PaymentConsentInlinePayeeInput:
oneOf:
- $ref: '#/components/schemas/PaymentConsentInlinePayeeInputNoneVerified'
- $ref: '#/components/schemas/PaymentConsentInlinePayeeInputClientVerified'
- $ref: '#/components/schemas/PaymentConsentInlinePayeeInputVerifiedVerified'
discriminator:
propertyName: verification_method
mapping:
NONE: '#/components/schemas/PaymentConsentInlinePayeeInputNoneVerified'
CLIENT_VERIFIED: '#/components/schemas/PaymentConsentInlinePayeeInputClientVerified'
VERIFICATION_TOKEN: '#/components/schemas/PaymentConsentInlinePayeeInputVerifiedVerified'
AppTokenId:
type: string
pattern: ^app_token_[a-z0-9]{25,27}$
description: Your App ID Token
example: app_token_c01234567890123456789012345
AuthorisationRequestSuccessResponse:
type: object
properties:
success:
type: boolean
enum:
- true
request_uri:
type: string
description: The pushed authorisation request_uri that should be specified in the authorisation URL.
authorisation_url:
type: string
format: uri
description: A pre-built authorisation URL that the user can be redirected to for authorisation, this includes the request_uri and any other necessary query parameters.
expires_in:
type: number
description: The number of seconds until the request URI expires.
required:
- success
- request_uri
- authorisation_url
- expires_in
CreateAuthorisationRequestIssueCode:
type: string
enum:
- invalid_request
- not_found
- single_limit_exceeded
- invalid_payee
- multiple_payees_not_supported
- account_payment_from_unsupported
PaymentConsentInlinePayeeInputVerifiedVerified:
type: object
properties:
source:
type: string
enum:
- INLINE
verification_method:
type: string
enum:
- VERIFICATION_TOKEN
description: " - `VERIFICATION_TOKEN` → The payee name and account number are\nverified using an Akahu account verification token. The details of payees verified in this way are sourced from the account verification token and cannot be modified by the client.\n - `NONE` → This verification method is restricted for use by specific clients.\n - `CLIENT_VERIFIED` → This verification method is restricted for use by specific clients."
verification_token:
type: string
required:
- source
- verification_method
- verification_token
EmailAddress:
type: string
format: email
OAuth500ErrorCode:
type: string
enum:
- server_error
Token:
type: object
description: Granted token details
properties:
success:
type: boolean
example: true
access_token:
type: string
description: Authorised **User Access Token** used to authenticate the user upon additional resource request.
example: user_token_1111111111111111111111111
token_type:
type: string
description: Type of authentication
example: bearer
scope:
type: string
description: whitespace separated string specifying the granted permissions and resources the given token has access to.
example: IDENTITY_BASIC ACCOUNTS TRANSACTIONS
OAuthInternalServerErrorResponse:
type: object
properties:
success:
type: boolean
enum:
- false
error:
$ref: '#/components/schemas/OAuth500ErrorCode'
error_description:
type: string
issues:
type: array
items:
type: object
properties:
code:
$ref: '#/components/schemas/OAuth500ErrorCode'
message:
type: string
path:
$ref: '#/components/schemas/IssuePath'
required:
- code
- message
- path
required:
- success
- error
- error_description
EnduringPaymentConsentRequest:
type: object
properties:
type:
type: string
enum:
- enduring_payment_consent
_user:
$ref: '#/components/schemas/UserId'
_account:
$ref: '#/components/schemas/AccountId'
payment_consent:
$ref: '#/components/schemas/EnduringPaymentConstraints'
required:
- type
- _user
- _account
AccessRequest:
oneOf:
- $ref: '#/components/schemas/EnduringAccessRequest'
- $ref: '#/components/schemas/EnduringPaymentConsentRequest'
discriminator:
propertyName: type
mapping:
enduring_access: '#/components/schemas/EnduringAccessRequest'
enduring_payment_consent: '#/components/schemas/EnduringPaymentConsentRequest'
ConnectionStubArray:
type: array
items:
$ref: '#/components/schemas/ConnectionStub'
EnduringAccessConstraints:
type: object
properties:
transactions:
$ref: '#/components/schemas/TransactionConstraints'
payments:
$ref: '#/components/schemas/EnduringAccessPaymentRequestApiView'
description: Any constraints on this access request.
OAuth401ErrorCode:
type: string
enum:
- invalid_client
EnduringPayee:
anyOf:
- $ref: '#/components/schemas/PaymentConsentStaticPayeeInput'
- $ref: '#/components/schemas/PaymentConsentRegisteredPayeeInput'
- $ref: '#/components/schemas/PaymentConsentInlinePayeeInput'
PaymentConsentRegisteredPayeeInput:
type: object
properties:
source:
type: string
enum:
- REGISTERED
_payee:
$ref: '#/components/schemas/PayeeId'
required:
- source
- _payee
OAuthUnauthorizedResponse:
type: object
properties:
success:
type: boolean
enum:
- false
error:
$ref: '#/components/schemas/OAuth401ErrorCode'
error_description:
type: string
issues:
type: array
items:
type: object
properties:
code:
$ref: '#/components/schemas/OAuth401ErrorCode'
message:
type: string
path:
$ref: '#/components/schemas/IssuePath'
required:
- code
- message
- path
required:
- success
- error
- error_description
PaymentConsentInlinePayeeInputNoneVerified:
type: object
properties:
source:
type: string
enum:
- INLINE
account_number:
$ref: '#/components/schemas/BankAccountNumber'
name:
type: string
minLength: 3
maxLength: 200
verification_method:
type: string
enum:
- NONE
description: " - `VERIFICATION_TOKEN` → The payee name and account number are\nverified using an Akahu account verification token. The details of payees verified in this way are sourced from the account verification token and cannot be modified by the client.\n - `NONE` → This verification method is restricted for use by specific clients.\n - `CLIENT_VERIFIED` → This verification method is restricted for use by specific clients."
required:
- source
- account_number
- name
- verification_method
TransactionConstraints:
type: object
properties:
start_date:
type: string
format: date
description: The start date for transactions to be requested from for new consents, this is in the Pacific/Auckland timezone.
required:
- start_date
description: Any constraints on transaction data that should be included in this access request, uses app defaults if not specified.
ConnectionsArray:
anyOf:
- $ref: '#/components/schemas/ConnectionIdArray'
- $ref: '#/components/schemas/ConnectionStubArray'
description: 'Which connections your application is requesting access to for this request.
Defaults to connections enabled for your application.'
OAuthResponseType:
type: string
enum:
- code
description: The response type to use for this request, only 'code' is supported.
EnduringAccessPaymentRequestApiView:
type: object
properties:
single_limit:
type: number
exclusiveMinimum: 0
description: The single payment limit for payments initiated under this consent.
periodic_limit:
$ref: '#/components/schemas/EnduringPaymentPeriodLimit'
payees:
type: array
items:
$ref: '#/components/schemas/EnduringPayee'
minItems: 1
description: The payees that are authorized to receive payments under this consent. At least one payee must be specified.
required:
- single_limit
- periodic_limit
- payees
description: The payment consent details for this request.
ConnectionIdArray:
type: array
items:
$ref: '#/components/schemas/ConnectionId'
PayeeId:
type: string
pattern: ^payee_[a-z0-9]{25,27}$
example: payee_c01234567890123456789012345
EnduringAccessScope:
type: string
enum:
- user:basic
- user:email
- identity:name
- identity:dob
- identity:email
- identity:phone
- identity:address
- identity:tax_number
- accounts:basic
- accounts:balance
- accounts:details
- accounts:owner
- transactions:credits
- transactions:debits
- payments
OAuthRedirectMode:
type: string
enum:
- default
- embedded
- deep_link
default: default
description: The mode of redirect to use when redirecting the user back to your application.
EnduringPaymentConstraints:
type: object
properties:
label:
type: string
default: Default
description: 'The label that groups these payment constraints.
This is used to help distinguish between multiple payment consents for the same account.
When re-consenting, this label will ensure that the old consent with the same label is replaced by the new one.'
single_limit:
type: number
exclusiveMinimum: 0
description: The single payment limit for payments initiated under this consent.
periodic_limit:
$ref: '#/components/schemas/EnduringPaymentPeriodLimit'
payees:
type: array
items:
$ref: '#/components/schemas/EnduringPayee'
minItems: 1
description: The payees that are authorized to receive payments under this consent, at least one payee must be specified.
required:
- single_limit
- periodic_limit
- payees
description: The payment consent details for this request.
PaymentConsentInlinePayeeInputClientVerified:
type: object
properties:
source:
type: string
enum:
- INLINE
account_number:
$ref: '#/components/schemas/BankAccountNumber'
name:
type: string
minLength: 3
maxLength: 200
verification_method:
type: string
enum:
- CLIENT_VERIFIED
description: " - `VERIFICATION_TOKEN` → The payee name and account number are\nverified using an Akahu account verification token. The details of payees verified in this way are sourced from the account verification token and cannot be modified by the client.\n - `NONE` → This verification method is restricted for use by specific clients.\n - `CLIENT_VERIFIED` → This verification method is restricted for use by specific clients."
required:
- source
- account_number
- name
- verification_method
ConnectionId:
type: string
format: cuid
pattern: ^conn_[a-z0-9]{25,27}$
example: conn_cjgaac5at000001qi2yw8ftil
description: The connected financial institution's unique identifier. This will always be prefixed with `conn_`.
OAuth400ErrorCode:
type: string
enum:
- invalid_request
- unsupported_response_type
- unsupported_grant_type
ConnectionStub:
type: string
enum:
- amex
- amex:classic
- anz
- anz:classic
- anz:official
- asb
- asb:classic
- asb:official
- bnz
- bnz:classic
- bnz:official
- booster
- booster:classic
- coop
- coop:classic
- demo_bank
- demo_bank:classic
- demo_bank:official
- fisher_funds
- fisher_funds:classic
- generate
- generate:classic
- hatch
- hatch:classic
- hatch:official
- heartland
- heartland:classic
- ird
- ird:classic
- pie_funds
- pie_funds:classic
- kernel
- kernel:classic
- kiwibank
- kiwibank:classic
- kiwibank:official
- latitude
- latitude:classic
- milford
- milford:classic
- nzhl
- nzhl:classic
- nzhl:official
- rabobank
- rabobank:classic
- sbs
- sbs:classic
- sharesies
- sharesies:classic
- sharesight
- sharesight:classic
- simplicity
- simplicity:classic
- stake
- stake:classic
- superlife
- superlife:classic
- tsb
- tsb:classic
- westpac
- westpac:classic
- westpac:official
- wise
- wise:classic
EnduringPaymentPeriodLimit:
type: object
properties:
amount:
type: number
exclusiveMinimum: 0
description: The amount that can be paid in the specified frequency period.
frequency:
$ref: '#/components/schemas/EnduringPaymentFrequency'
required:
- amount
- frequency
description: The periodic payment limit for payments initiated under this consent.
CreateAuthorisationRequestInvalidRequestResponse:
type: object
properties:
success:
type: boolean
enum:
- false
error:
$ref: '#/components/schemas/OAuth400ErrorCode'
error_description:
type: string
issues:
type: array
items:
type: object
properties:
code:
$ref: '#/components/schemas/CreateAuthorisationRequestIssueCode'
message:
type: string
path:
$ref: '#/components/schemas/IssuePath'
required:
- code
- message
- path
required:
- success
- error
- error_description
UserId:
type: string
pattern: ^user_[a-z0-9]{25,27}$
example: user_c01234567890123456789012345
PaymentConsentStaticPayeeInput:
type: object
properties:
source:
type: string
enum:
- STATIC
account_number:
$ref: '#/components/schemas/BankAccountNumber'
required:
- source
- account_number
EnduringLoginHint:
anyOf:
- $ref: '#/components/schemas/EmailAddress'
- $ref: '#/components/schemas/UserId'
description: 'A login hint to suggest a user to use for ''enduring_access'' requests. This will be ignored for other request types.
The user may choose to authenticate as a different Akahu user than specified.
This may be in the form of an email address or an Akahu User ID.'
EnduringPaymentFrequency:
type: string
enum:
- DAILY
- WEEKLY
- FORTNIGHTLY
- MONTHLY
- ANNUALLY
description: The frequency at which the periodic limit applies, this is used in combination with the amount to determine the periodic limit. (E.g. $1 daily)
BankAccountNumber:
type: string
pattern: ^\d{2}-\d{4}-\d{7}-\d{2,3}$
IssuePath:
type: array
items:
title: IssuePathSegment
oneOf:
- type: string
- type: number
parameters:
xAkahuId:
name: X-Akahu-Id
in: header
required: true
description: Your **App ID Token**.
schema:
type: string
example: '{{app_token}}'
responses:
'400':
description: Your request was malformed or otherwise unacceptable. More details are provided under the `message` key in the response.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
message:
type: string
example: Invalid Content-Type
'500':
description: An internal error has prevented us from processing the request. More detail may be supplied in the `message` key.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
message:
type: string
example: Something went wrong
'401':
description: You are not authorised to access this content.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
message:
type: string
example: Permission Denied
'403':
description: You are not allowed to access this content.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
message:
type: string
example: Forbidden
securitySchemes:
user_token:
type: http
scheme: bearer
description: 'User-level Authentication:
Http Bearer Auth with the token being a consented **User Access Token**.
> `Bearer {user_token}`
This will allow you to act on a **user''s** behalf when accessing the API.'
app_auth:
type: http
scheme: basic
description: 'App-level Authentication:
HTTP Basic Auth with the username being your **App ID Token** and the password being your **App Secret**.
> `Basic {app_token}:{app_secret}`
This will allow you to act as your Akahu **application**, rather than as a specific user.'
x-provenance:
method: searched
source: https://developers.akahu.nz/reference
harvested: '2026-10-26'
tool: harvest-readme-openapi.py
note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
assembled_from:
- https://developers.akahu.nz/reference/delete_accounts-id-payment-consents-consent-id.md
- https://developers.akahu.nz/reference/delete_accounts-id-verification-token.md
- https://developers.akahu.nz/reference/delete_authorisations-id.md
- https://developers.akahu.nz/reference/delete_token.md
- https://developers.akahu.nz/reference/delete_webhooks-id.md
- https://developers.akahu.nz/reference/get_accounts-id-transactions-pending.md
- https://developers.akahu.nz/reference/get_accounts-id-transactions.md
- https://developers.akahu.nz/reference/get_accounts-id-verification-token.md
- https://developers.akahu.nz/reference/get_accounts-id.md
- https://developers.akahu.nz/reference/get_accounts.md
- https://developers.akahu.nz/reference/get_categories-id.md
- https://developers.akahu.nz/reference/get_categories.md
- https://developers.akahu.nz/reference/get_connections-id.md
- https://developers.akahu.nz/reference/get_connections.md
- https://developers.akahu.nz/reference/get_identity-id.md
- https://developers.akahu.nz/reference/get_keys-id.md
# --- truncated at 32 KB (33 KB total) ---
# Full source: https://artifacts.apis.io/akahu/openapi/akahu-auth-api-openapi.yml