Akahu Connections API

openapi: 3.2.0
info:
  title: Akahu Connections API
  version: 1.0.0
  description: 'Operations tagged Connections across 2 of this provider''s published API definitions: akahu-enduring-api-openapi.yml, akahu-one-off-payments-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.akahu.io/v1
- description: Akahu One-off Payments API
  url: https://api.payments.akahu.io
tags:
- name: Connections
paths:
  /connections:
    get:
      tags:
      - Connections
      summary: Get all connections
      security:
      - app_auth: []
      description: '> ⚠️

        >

        > **Authentication**

        > This endpoint requires app-scoped authentication.


        Gets a list of all connected financial institutions that users can connect to your Akahu application.


        - 📚 Supported Integrations List'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  items:
                    type: array
                    description: List all financial institutions that users can connect to your application.
                    items:
                      $ref: '#/components/schemas/Connection'
                    example:
                    - _id: conn_cjgaaqcna000001ldwof8tvj0
                      name: ASB
                      logo: https://cdn.akahu.nz/logos/connections/conn_cjgaaqcna000001ldwof8tvj0
                      connection_type: classic
                      new_connections_enabled: false
                    - _id: conn_cm4hlog270000914n33hj6tqq
                      _classic: conn_cjgaaqcna000001ldwof8tvj0
                      name: ASB
                      logo: https://cdn.akahu.nz/logos/connections/conn_cm4hlog270000914n33hj6tqq
                      connection_type: official
                      new_connections_enabled: true
                      mode: migration
                      deadline: '2025-12-31'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
      operationId: getConnections
      x-operation-id-source: derived
    servers:
    - url: https://api.akahu.io/v1
  /connections/{id}:
    parameters:
    - name: id
      in: path
      required: true
      description: An Akahu Connection ID
      example: conn_1111111111111111111111111
      schema:
        type: string
    get:
      tags:
      - Connections
      summary: Get a connection
      security:
      - app_auth: []
      description: '> ⚠️

        >

        > **Authentication**

        > This endpoint requires app-scoped authentication.


        Get an individual financial institution connection.


        - 📚 Supported Integrations List'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  item:
                    description: Information about a specific financial institution that can be connected via Akahu
                    $ref: '#/components/schemas/Connection'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
      operationId: getConnectionsById
      x-operation-id-source: derived
    servers:
    - url: https://api.akahu.io/v1
  /v1/connections:
    get:
      operationId: GetConnections
      tags:
      - Connections
      summary: Get available connections
      description: Get the financial institution connections available to this application for one-off payments.
      deprecated: false
      security:
      - AppSecret: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OneOffPaymentConnectionsResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Generic400ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Generic401ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Generic403ErrorResponse'
    servers:
    - description: Akahu One-off Payments API
      url: https://api.payments.akahu.io
components:
  schemas:
    Connection:
      type: object
      properties:
        _id:
          $ref: '#/components/schemas/ConnectionId'
        _classic:
          type: string
          format: cuid
          pattern: ^conn_[a-z0-9]{25,27}$
          example: conn_c01234567890123456789012344
          description: 'The ID of the corresponding classic connection for this institution.


            This is only present for official open banking connections (Read more [here](/docs/official-open-banking)).'
        name:
          type: string
          description: Display name for the connected institution.
          example: My Bank
        logo:
          type: string
          format: uri
          description: A URL pointing to an image of the institution's logo.
          example: https://cdn.akahu.nz/logos/connections/conn_cjgaac5at000001qi2yw8ftil
        connection_type:
          $ref: '#/components/schemas/ConnectionType'
        new_connections_enabled:
          type: boolean
          description: 'Whether new connections to this institution are allowed.


            This may be `false` if your app is configured to migrate users to the official open banking connection for this provider.'
          example: true
        mode:
          type: string
          description: 'The migration mode of this connection.


            This is only present for official open banking connections (Read more [here](/docs/official-open-banking)).


            The `mode` will be one of:


            - `strict` The classic equivalent of this connection is not available to your users. This mode can only be configured for new apps or apps that have successfully migrated all users away from their existing classic connections for this provider.


            - `migration` Any existing classic connections to this provider will continue to operate, but users will be unable to set up a new classic connection for this provider. New connections can only be established using this official open banking connection.


            - `side_by_side` Your users will be able to choose when setting up a new connection whether they wish to use the classic or official open banking connection for this provider. This mode is useful for apps that want to enable an official open banking connection where possible, but provide a fallback for users with account types that are not yet supported by the official open banking connection.


            - `developer` This is like migration mode, but will allow developers to continue to connect classic connections, so that they can test the migration process. This mode can only be enabled in non-production environments.'
          enum:
          - strict
          - migration
          - side_by_side
          - developer
          example: migration
        deadline:
          type: string
          description: 'The deadline date for users to migrate from classic to official open banking connections.


            This is only present for official open banking connections in `migration` or `developer` mode (Read more [here](/docs/official-open-banking)).'
          example: '2025-12-31'
      required:
      - _id
      - name
      - logo
      - connection_type
      - new_connections_enabled
    ConnectionType:
      type: string
      description: 'The type of integration used to connect to this institution.


        This will be one of:

        - `classic` A classic Akahu connection, which uses Akahu''s custom built integration to connect to the institution.

        - `official` An official open banking connection, which uses the institution''s official open banking APIs.'
      enum:
      - classic
      - official
      example: official
    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_`.
    Generic401ErrorResponseCode:
      type: string
      enum:
      - unauthorized
    Generic403ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
          - false
        message:
          type: string
        issues:
          type: array
          items:
            type: object
            properties:
              code:
                $ref: '#/components/schemas/Generic403ErrorResponseCode'
              message:
                type: string
              path:
                $ref: '#/components/schemas/IssuePath'
            required:
            - code
            - message
            - path
      required:
      - success
      - message
      - issues
    Generic401ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
          - false
        message:
          type: string
        issues:
          type: array
          items:
            type: object
            properties:
              code:
                $ref: '#/components/schemas/Generic401ErrorResponseCode'
              message:
                type: string
              path:
                $ref: '#/components/schemas/IssuePath'
            required:
            - code
            - message
            - path
      required:
      - success
      - message
      - issues
    Generic400ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
          - false
        message:
          type: string
        issues:
          type: array
          items:
            type: object
            properties:
              code:
                $ref: '#/components/schemas/Generic400ErrorResponseCode'
              message:
                type: string
              path:
                $ref: '#/components/schemas/IssuePath'
            required:
            - code
            - message
            - path
      required:
      - success
      - message
      - issues
    Generic400ErrorResponseCode:
      type: string
      enum:
      - invalid
      - invalid_id
      - not_found
      - bad_request
      - invalid_type
      - invalid_literal
      - invalid_union
      - invalid_union_discriminator
      - invalid_enum_value
      - unrecognized_keys
      - invalid_arguments
      - invalid_return_type
      - invalid_date
      - invalid_string
      - too_small
      - too_big
      - invalid_intersection_types
      - not_multiple_of
      - not_finite
    OneOffPaymentConnection:
      type: object
      properties:
        _id:
          $ref: '#/components/schemas/ConnectionId_2'
        bank:
          allOf:
          - $ref: '#/components/schemas/OneOffPaymentBank'
          - description: The value to provide as payer.bank when creating a one-off payment.
            example: westpac
        name:
          type: string
          description: The name of the institution.
          example: Westpac
        logo:
          type: string
          format: uri
          description: A URL pointing to an image of the institution's logo.
        limits:
          type: object
          properties:
            oneoff:
              type: array
              items:
                $ref: '#/components/schemas/OneOffPaymentLimit'
          required:
          - oneoff
      required:
      - _id
      - bank
      - name
      - logo
      - limits
    OneOffPaymentConnectionsResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
          - true
        items:
          type: array
          items:
            $ref: '#/components/schemas/OneOffPaymentConnection'
      required:
      - success
      - items
    OneOffPaymentLimit:
      type: object
      properties:
        value:
          type: number
          exclusiveMinimum: 0
          description: The limit amount in dollars.
          example: 30000
        type:
          $ref: '#/components/schemas/OneOffPaymentLimitType'
        classification:
          $ref: '#/components/schemas/PaymentLimitClassification'
        description:
          type: string
          description: Additional context about how the limit is applied.
      required:
      - value
      - type
      - classification
      - description
    OneOffPaymentBank:
      type: string
      enum:
      - anz
      - asb
      - bnz
      - kiwibank
      - nzhl
      - westpac
      - demo_bank
      description: The bank the customer must use to make this payment
    OneOffPaymentLimitType:
      type: string
      enum:
      - single_payment
      - daily
      - weekly
      description: The payment or time period that the limit applies to.
    PaymentLimitClassification:
      type: string
      enum:
      - strict
      - informational
      description: How the published value should be interpreted. A `strict` value is a fixed upper bound. An `informational` value is a default or indicative amount and the customer's actual limit may differ.
    ConnectionId_2:
      type: string
      pattern: ^conn_[a-z0-9]{25,27}$
      example: conn_c01234567890123456789012345
    Generic403ErrorResponseCode:
      type: string
      enum:
      - forbidden
    IssuePath:
      type: array
      items:
        title: IssuePathSegment
        oneOf:
        - type: string
        - type: number
  responses:
    '404':
      description: The item you are trying to access doesn't exist.
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              message:
                type: string
                example: Not Found
    '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
    '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
    '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
    '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
  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-refined-from:
- akahu-enduring-api-openapi.yml
- akahu-one-off-payments-api-openapi.yml
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/archiveapplication.md
  - https://developers.akahu.nz/reference/createapplication.md
  - https://developers.akahu.nz/reference/createdatafile.md
  - https://developers.akahu.nz/reference/createdocument.md
  - https://developers.akahu.nz/reference/createreferral.md
  - https://developers.akahu.nz/reference/createreferralredemption.md
  - https://developers.akahu.nz/reference/createreport.md
  - https://developers.akahu.nz/reference/createsharingrequest.md
  - https://developers.akahu.nz/reference/deletedatafile.md
  - https://developers.akahu.nz/reference/deletedocument.md
  - https://developers.akahu.nz/reference/downloaddatafile.md
  - https://developers.akahu.nz/reference/downloaddocument.md
  - https://developers.akahu.nz/reference/getapplication.md
  - https://developers.akahu.nz/reference/getcurrentorg.md
  - https://developers.akahu.nz/reference/getdatafile.md
  - https://developers.akahu.nz/reference/getdocument.md
  - https://developers.akahu.nz/reference/getreferral.md
  - https://developers.akahu.nz/reference/getreferralredemption.md
  - https://developers.akahu.nz/reference/getreport.md
  - https://developers.akahu.nz/reference/getreportaccounts.md
  - https://developers.akahu.nz/reference/getreportdatasources.md
  - https://developers.akahu.nz/reference/getreporthtmldownload.md
  - https://developers.akahu.nz/reference/getreportinsights.md
  - https://developers.akahu.nz/reference/getreportjsondownload.md
  - https://developers.akahu.nz/reference/getreporttransactions.md
  - https://developers.akahu.nz/reference/getsharingrequest.md
  - https://developers.akahu.nz/reference/listdatafiles.md
  - https://developers.akahu.nz/reference/listdocuments.md
  - https://developers.akahu.nz/reference/listreferrals.md
  - https://developers.akahu.nz/reference/listresources.md
  - https://developers.akahu.nz/reference/revokereferral.md
  - https://developers.akahu.nz/reference/unarchiveapplication.md
  - https://developers.akahu.nz/reference/updateapplication.md
  merge:
    pages: 33
    deduped: 2607
    conflicts_kept_first: 0