The account authorization object

{
  "id": "aauth_01JEXAMPLE2K8V4N9C6M1Q7R",
  "object": "account_authorization",
  "status": "pending",
  "authorization_url": "https://…",
  "permissions": [],
  "expires_at": "2026-01-01T00:00:00Z",
  "livemode": false
}

{
  "id": "id_01JEXAMPLE2K8V4N9C6M1Q7R",
  "object": "account_authorization",
  "status": "approved",
  "account": "mer_01JEXAMPLE2K8V4N9C6M1Q7R",
  "permissions": [],
  "livemode": false
}

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. 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. The returned ID identifies a connected account. Both requests use your platform secret key without Ionic-Account.

Attributes

When you start an authorization

string

Unique identifier for the authorization (aauth_…).

string

Authorization status. A newly created authorization is pending until the account holder approves it.

string

Browser URL to open for the Account holder.

array of strings

Permissions your platform requested from the account holder.

string

ISO 8601 date-time when the authorization expires if it has not been approved.

When you exchange the code

string

Authorization status. An exchanged authorization is approved.

string

Ionic Account ID to use with supported Platform API calls.

array of strings

Permissions granted by the connected Account.

Endpoints

Endpoint	Use it for
Start existing-Account authorization	Create the authorization request and get the `authorization_url` to redirect the merchant to.
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.
Approval connects the merchant; it does not activate their payment capability. Read the connected account to check payments_enabled before offering payment features.

Fundamentals

Payments

Checkout

In-person payments

Customers and catalog

Connect

Billing

Webhooks

The account authorization object

Attributes

When you start an authorization

When you exchange the code

Endpoints

Statuses

Rules

​Attributes

​When you start an authorization

​When you exchange the code

​Endpoints

​Statuses

​Rules

Attributes

When you start an authorization

When you exchange the code

Endpoints

Statuses

Rules