> ## 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.

# Exchange an Account-approved code

> Consumes the one-time callback code with the original PKCE verifier and
exact redirect URI. A successful response identifies the connected
Account and the permissions it granted. The exchange delivers an
already-approved result; it does not create or expand access.




## OpenAPI

````yaml /openapi/connect.yaml post /account_authorizations/{id}/exchange
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/{id}/exchange:
    post:
      tags:
        - Account Authorizations
      summary: Exchange an Account-approved code
      description: |
        Consumes the one-time callback code with the original PKCE verifier and
        exact redirect URI. A successful response identifies the connected
        Account and the permissions it granted. The exchange delivers an
        already-approved result; it does not create or expand access.
      operationId: exchangeAccountAuthorization
      parameters:
        - $ref: '#/components/parameters/AccountAuthorizationId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExchangeAccountAuthorizationRequest'
            example:
              code: code_issued_in_the_callback
              code_verifier: UxKhyxMfJm0YdZQp0zJ9CqDgL8XsBYH1NlM5Q7PTW2A
              redirect_uri: https://platform.example/connect/callback
      responses:
        '200':
          description: The approved authorization result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountAuthorizationExchange'
        '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:
    AccountAuthorizationId:
      name: id
      in: path
      required: true
      description: Account authorization ID.
      schema:
        type: string
        pattern: ^aauth_[0-9A-Za-z]{24}$
    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:
    ExchangeAccountAuthorizationRequest:
      type: object
      additionalProperties: false
      required:
        - code
        - code_verifier
        - redirect_uri
      properties:
        code:
          type: string
          minLength: 1
          description: One-time code from the redirect callback.
        code_verifier:
          type: string
          minLength: 43
          maxLength: 128
          description: Original PKCE verifier used to derive the code challenge.
        redirect_uri:
          type: string
          format: uri
          description: Exact URI supplied when the authorization was created.
    AccountAuthorizationExchange:
      type: object
      additionalProperties: false
      required:
        - id
        - object
        - status
        - account
        - permissions
        - livemode
      properties:
        id:
          type: string
          pattern: ^aauth_[0-9A-Za-z]{24}$
        object:
          type: string
          enum:
            - account_authorization
        status:
          type: string
          enum:
            - approved
        account:
          type: string
          pattern: ^mer_[0-9A-Za-z]{14}$
          description: Ionic Account ID to use with supported Platform API calls.
        permissions:
          type: array
          items:
            type: string
          description: Permissions granted by the connected Account.
        livemode:
          type: boolean
    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>`.

````