Anatomy of an authorisation request

Akahu supports two methods for creating an OAuth authorisation request.

An inline authorisation request is the simplest method and most suitable for applications that request read-only access without the need for fine-grained control over each request.

A Pushed Authorisation Request (PAR) allows for fine-grained control over the scope of access requested of each user, and is most suitable for advanced use cases and enduring payment consent requests.

The right method depends on how much control you need over the access requested from each user.

Common authorisation request parameters

Both the inline and PAR authorisation request types share a common set of top-level parameters:

Inline authorisation request

Inline authorisation requests are constructed by building an authorisation URL with the authorisation request parameters included in the URL query string. Your application navigates the user to this URL to complete authorisation.

Akahu's base authorisation URL is https://oauth.akahu.nz.

In addition to the common request parameters, Akahu's inline authorisation request accepts the following parameters:

Example inline authorisation request

https://oauth.akahu.nz?
  response_type=code
  &client_id=app_token_1234567890987654321
  &email=user%40example.com
  &redirect_uri=https%3A%2F%2Fexample.com%2Fauth%2Fakahu
  &scope=ENDURING_CONSENT
  &state=1234567890

📘

URL encoding: All authorisation URL parameters must be URL encoded.

💡

In most cases it is only necessary to supply the "access request type" of either ENDURING_CONSENT or ONEOFF in the scope parameter. When you do this, Akahu will automatically populate the request with the full list of scopes that your app is configured with. If you wish to only request a subset of your app's available scopes, simply set the scope parameter to a space-separated list of the scopes you desire (including the access request type as well).

Pushed authorisation request (PAR)

The Pushed Authorisation Request (PAR) extension facilitates the construction of an authorisation request via a server-to-server POST request. One of the advantages of PAR is that a much greater level of detail can be included in each authorisation request. This means that the scope of access requested can be highly customised and configurable on a per-user basis.

PAR is best suited to Akahu developers who need fine-grained control over the access being requested. This is particularly important for applications that require bespoke enduring payment consents (e.g. varying limits or payees) for each user.

A PAR is created by submitting a request to the POST /v1/par endpoint. In response, Akahu's authorisation server returns an authorisation_url. Navigate your user to the authorisation_url to complete authorisation of the request.

ℹ️

PAR is currently only available for enduring access requests.

In addition to the common request parameters, Akahu's PAR implementation accepts the following parameters:

Example pushed authorisation request

POST /v1/par HTTP/1.1
Host: api.akahu.io
Content-Type: application/json

{
  "client_id": "{{app_token}}",
  "client_secret": "{{app_secret}}",
  "response_type": "code",
  "redirect_uri": "https://example.com/auth/akahu",
  "redirect_mode": "deep_link",  // For native mobile redirect URIs
  "state": "123e4567-e89b-12d3-a456-426614174000",
  "login_hint": "[email protected]",
  "request": {
    // Access request (see below)
  }
}

📘

The PAR endpoint is authenticated by the client_id and client_secret included in the request body. No Authorization header is required.

Access requests

The specific type and scope of access being requested is defined by the request parameter (aka the Access Request). This parameter is a non-standard, Akahu-specific extension to the OAuth protocol, although it is heavily inspired by the Rich Authorisation Request (RAR) proposal.

The schema of each access request is determined by the top-level access request type parameter. Currently, two types of access request are supported: enduring_access and enduring_payment_consent.

Enduring access

The enduring_access access request is equivalent to the ENDURING_CONSENT inline request type. This is a general purpose access request that can include both account information and enduring payment scopes.

An enduring_access request can be used to request authorisation from new users of your application as well as allow existing users to modify their authorisation (e.g. by adding or removing accounts).

The enduring_access request type includes the following parameters.

Example: account information

{
  "type": "enduring_access",
  "scope": [
    "user:basic",           // Basic Akahu user info (e.g. user ID)
    "accounts:basic",       // Basic account details
    "accounts:balance",     // Account balances
    "transactions:credits", // Transaction data (credits)
    "transactions:debits"   // Transaction data (debits)
  ],
  "constraints": {
    "transactions": {
      // The historical start date for transactions access
      "start_date": "2026-01-01"
    }
  }
}

ℹ️

The transactions constraint is optional. If omitted, the transactions start_date for the access request will be set to the default historical period configured for your application.

Example: account information + enduring payments

{
  "type": "enduring_access",
  "scope": [
    "user:basic",       // Basic Akahu user info (e.g. user ID)
    "accounts:basic",   // Basic account details such as account name and number
    "accounts:balance", // Account balances
    "payments"          // Enduring payment initiation
  ],
  "constraints": {
    "payments": {
      // The single payment limit being requested
      "single_limit": 1000,
      // The periodic payment limit being requested
      "periodic_limit": {
        "amount": 1000,
        "frequency": "DAILY"
      },
      // The payees to be included in the payment consent
      "payees": [
        {
          "source": "STATIC",
          "account_number": "12-1234-1234567-12"
        }
      ]
    }
  }
}

ℹ️

If your application has a default payment consent request configured, the payments constraint is optional. If omitted, the access request will use your application's default payment consent request.

Each entry in payees specifies an account this consent is allowed to pay, and must be supplied from a verified source. See Payee Verification for the available payee sources, and Enduring Payments for the end-to-end payment flow.

Enduring payment consent

The enduring_payment_consent access request allows your application to request user authorisation of an enduring payment consent for a specific account that the user has previously shared with your application.

This access request type makes it simple to retroactively add and modify enduring payment consents for a user's connected accounts. It is useful in scenarios where the user completes an initial enduring_access authorisation without granting payments access and for use-cases where payment consent parameters aren't known at the time of initial user authorisation.

The enduring_payment_consent request type includes the following parameters.

Example: Enduring payment consent

{
  "type": "enduring_payment_consent",
  "_user": "user_1234567890987654321",
  "_account": "acc_1234567890987654321",
  "payment_consent": {
    // Identifies the consent. Re-consenting with the same label replaces it.
    "label": "Default",
    "single_limit": 1000,
    "periodic_limit": {
      "amount": 1000,
      "frequency": "DAILY"
    },
    "payees": [
      {
        "source": "STATIC",
        "account_number": "12-1234-1234567-12"
      }
    ]
  }
}