> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionicfi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Start existing-Account authorization

> Creates a short-lived authorization request. Send the Account holder to
`authorization_url`. After they approve or deny access, Ionic redirects
to your exact `redirect_uri` with the original `state` and either a
one-time `code` or an `error`.




## OpenAPI

````yaml /openapi/connect.yaml post /account_authorizations
openapi: 3.0.3
info:
  title: Ionic Connect API
  version: '2026-09-02'
  description: |
    Connect an existing Ionic Account to a Platform and read the Accounts that
    have granted that Platform access.

    These endpoints require the Platform's Connect secret key. The key and its
    test or live mode identify the Platform; `Ionic-Account` is not accepted on
    this surface. Authorization uses a browser redirect with PKCE. Store the
    original `state` and PKCE verifier before sending the Account holder to the
    returned `authorization_url`, then validate `state` and exchange the
    one-time code after Ionic redirects back.
servers:
  - url: '{baseUrl}/v1'
    variables:
      baseUrl:
        default: https://api.ionicfi.com
        description: API base URL for your environment.
security:
  - secretKey: []
tags:
  - name: Account Authorizations
    description: Ask an existing Account to authorize a Platform.
  - name: Connected Accounts
    description: Accounts that currently authorize the Platform.
paths:
  /account_authorizations:
    post:
      tags:
        - Account Authorizations
      summary: Start existing-Account authorization
      description: |
        Creates a short-lived authorization request. Send the Account holder to
        `authorization_url`. After they approve or deny access, Ionic redirects
        to your exact `redirect_uri` with the original `state` and either a
        one-time `code` or an `error`.
      operationId: createAccountAuthorization
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAccountAuthorizationRequest'
            example:
              redirect_uri: https://platform.example/connect/callback
              state: s_7d897c12c77d4d5a
              code_challenge: 7Z6G4Lw3Azhfy6YkUkP2-kd5Yq4VrMc9Mfq0GvPK81A
              code_challenge_method: S256
              permissions:
                - payments:read
                - payments:write
      responses:
        '201':
          description: The authorization request and browser URL.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountAuthorization'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
        - secretKey:
            - platform:act
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      description: A unique key that makes a retry return the original result.
      schema:
        type: string
        minLength: 1
        maxLength: 255
  schemas:
    CreateAccountAuthorizationRequest:
      type: object
      additionalProperties: false
      required:
        - redirect_uri
        - state
        - code_challenge
        - code_challenge_method
        - permissions
      properties:
        redirect_uri:
          type: string
          format: uri
          pattern: ^https://[^/?#]+/connect/callback$
          description: Exact HTTPS callback registered for the Platform.
        state:
          type: string
          minLength: 1
          maxLength: 512
          description: >-
            Opaque value your callback must verify against the value stored
            before redirecting.
        code_challenge:
          type: string
          minLength: 43
          maxLength: 43
          description: >-
            Base64url-encoded SHA-256 digest of the PKCE verifier, without
            padding.
        code_challenge_method:
          type: string
          enum:
            - S256
        permissions:
          type: array
          minItems: 1
          maxItems: 50
          uniqueItems: true
          items:
            type: string
          description: Permissions the Platform asks the Account holder to grant.
    AccountAuthorization:
      type: object
      additionalProperties: false
      required:
        - id
        - object
        - status
        - channel
        - livemode
        - permissions
        - authorization_url
        - created_at
        - expires_at
      properties:
        id:
          type: string
          pattern: ^aauth_[0-9A-Za-z]{24}$
        object:
          type: string
          enum:
            - account_authorization
        status:
          type: string
          enum:
            - pending
        channel:
          type: string
          enum:
            - platform_redirect
        livemode:
          type: boolean
        permissions:
          type: array
          items:
            type: string
        authorization_url:
          type: string
          format: uri
          description: Browser URL to open for the Account holder.
        created_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
  responses:
    BadRequest:
      description: >-
        Invalid fields, PKCE data, callback data, permissions, or pagination
        cursor.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: The credential cannot perform this Connect operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: >-
        The authorization or Account relationship changed and the operation
        cannot continue.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Too many requests.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    secretKey:
      type: http
      scheme: bearer
      description: >-
        A Platform Connect secret key (`sk_…`) sent as `Authorization: Bearer
        <key>`.

````