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

# The account authorization object

> Let an existing Ionic merchant authorize your platform and return its merchant ID.

<ResponseExample>
  ```json When you start an authorization theme={null}
  {
    "id": "aauth_01JEXAMPLE2K8V4N9C6M1Q7R",
    "object": "account_authorization",
    "status": "pending",
    "authorization_url": "https://…",
    "permissions": [],
    "expires_at": "2026-01-01T00:00:00Z",
    "livemode": false
  }
  ```

  ```json When you exchange the code theme={null}
  {
    "id": "id_01JEXAMPLE2K8V4N9C6M1Q7R",
    "object": "account_authorization",
    "status": "approved",
    "account": "mer_01JEXAMPLE2K8V4N9C6M1Q7R",
    "permissions": [],
    "livemode": false
  }
  ```
</ResponseExample>

An account authorization (`aauth_…`) is a short-lived request that asks an
existing Ionic merchant to grant your platform access. Your server creates it
and redirects the merchant's browser to the returned `authorization_url`. After
the merchant approves or denies, Ionic redirects to your `redirect_uri` with
the original `state` and either a one-time `code` or an `error`. Your server
exchanges the code for the merchant's `mer_…` ID and the permissions it
granted. For the full flow, see [Connect an existing merchant](/guides/connect-a-merchant).

This flow connects an existing account; it does not create one. To bring a
business that is new to Ionic onto your platform, use an
[Account Link](/api-reference/account-links). The returned ID identifies a
[connected account](/api-reference/connected-accounts). Both requests use your
platform secret key without `Ionic-Account`.

## Attributes

### When you start an authorization

<ResponseField name="id" type="string">
  Unique identifier for the authorization (`aauth_…`).
</ResponseField>

<ResponseField name="status" type="string">
  Authorization status. A newly created authorization is `pending` until the account holder approves it.
</ResponseField>

<ResponseField name="authorization_url" type="string">
  Browser URL to open for the Account holder.
</ResponseField>

<ResponseField name="permissions" type="array of strings">
  Permissions your platform requested from the account holder.
</ResponseField>

<ResponseField name="expires_at" type="string">
  ISO 8601 date-time when the authorization expires if it has not been approved.
</ResponseField>

### When you exchange the code

<ResponseField name="status" type="string">
  Authorization status. An exchanged authorization is `approved`.
</ResponseField>

<ResponseField name="account" type="string">
  Ionic Account ID to use with supported Platform API calls.
</ResponseField>

<ResponseField name="permissions" type="array of strings">
  Permissions granted by the connected Account.
</ResponseField>

## Endpoints

| Endpoint | Use it for |
| - | - |
| [Start existing-Account authorization](/api-reference/account-authorizations/start-existing-account-authorization) | Create the authorization request and get the `authorization_url` to redirect the merchant to. |
| [Exchange an Account-approved code](/api-reference/account-authorizations/exchange-an-account-approved-code) | Exchange the callback code for the connected account's ID and granted permissions. |

## Statuses

| Status | Meaning |
| - | - |
| `pending` | Returned when you start the authorization request, with the `authorization_url`. |
| `approved` | Returned by a successful exchange. The response includes `account` and `permissions`. |

## Rules

* Create a random, single-use `state` and a PKCE verifier for each attempt.
  `code_challenge` is the base64url-encoded SHA-256 digest of the verifier,
  without padding, and `code_challenge_method` is `S256`. Keep the verifier on
  your server.
* Verify that `state` matches the pending attempt before accepting a result.
  If the merchant denies access, do not exchange a code.
* `redirect_uri` must be a redirect domain you added under **Connect → Domains**
  followed by `/connect/callback`, with no query string or fragment. Redirect
  domains are separate from payment domains.
* The exchange takes the callback `code`, the original `code_verifier`, and the
  exact `redirect_uri` from the start request. A code is single-use.
* Requested permissions must be allowed by your Platform Program. They do not
  expand your API key's permissions.
* The exchange delivers an already-approved result. It does not create or expand
  access, and it does not return a new API key.
* Send an `Idempotency-Key` on both requests. When retrying, preserve the key
  and body. See [Idempotency](/api-reference/idempotency).
* Approval connects the merchant; it does not activate their payment capability.
  Read the [connected account](/api-reference/connected-accounts) to check
  `payments_enabled` before offering payment features.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.