> Markdown version of https://authpi.com/docs/reference/core-api/accounts/ — fetch the complete AuthPI docs index at https://authpi.com/llms.txt to discover all available pages.

# Accounts — AuthPI Core API

Account management endpoints. An Account is your billing and administrative entity in AuthPI—it contains Issuers, manages billing, and holds administrative memberships.

## GET /v1/accounts

**List Accounts**

List all accounts the authenticated user has access to

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | Optional |  |
| `cursor` | string | Optional |  |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Accounts retrieved successfully | `object` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |

## GET /v1/accounts/{account_id}

**Get Account**

Retrieve an account by ID

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | Account ID |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Account retrieved successfully | `object` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## PATCH /v1/accounts/{account_id}

**Update Account**

Update an account's settings

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | Account ID |

### Request body

Content type: `application/json`

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `owner_user_id` | string | Optional | User ID |
| `domains` | object[] | Optional |  |
| `metadata` | Metadata | Optional |  |
| `name` | string \| null | Optional | A name for the resource. |
| `description` | string \| null | Optional | A description for the resource. Markdown supported. |
| `logo_url` | string \| null | Optional | A URL |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Account updated successfully | `object` |
| 400 | **Bad Request** - The request is malformed or contains invalid data. | `ApiError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |
| 412 | **Precondition Failed** - The resource has been modified since the provided ETag. | `PreconditionFailedError` |

## GET /v1/accounts/{account_id}/credits/ledger

**List Account Credit Ledger**

List account credit ledger entries, most recent first

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | Account ID |

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | Optional |  |
| `cursor` | string | Optional |  |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Credit ledger retrieved successfully | `object` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## POST /v1/accounts/{account_id}/credits/topups

**Create Account Credit Top-up**

Settle an x402 payment and add prepaid credits to the account

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | Account ID |

### Request body

Content type: `application/json`

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_μusd` | integer | Required |  |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Credit top-up settled successfully | `object` |
| 400 | Invalid request | — |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 402 | x402 payment required (challenge), payer wallet not in the method's allowlist, or settlement failed at the facilitator | — |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |
| 409 | Payment method was revoked or its allowlist tightened between the on-chain settlement and the credit write. The payment is recorded on-chain (response includes payment_reference) and queued for manual reconciliation; do not retry — contact support with the payment_reference. | — |
| 502 | x402 facilitator unavailable | — |

## POST /v1/accounts/{account_id}/payment-methods

**Add x402 Payment Method**

Register an x402 payment method on the account. At most one active x402 method per account.

**Implicit `billing_mode` change:** `billing_mode` is derived from the count of active payment methods (gated when ≥1, ungated when 0), unless an operator override is set. Adding the first method on an account flips the derived `billing_mode` to `"gated"` automatically; removing the only method flips it back to `"ungated"`. There is no public API to write `billing_mode` directly — operators with a need to pin it (e.g. force-ungated for a grandfathered customer) use the internal `setGatingOverride` RPC.

**Stripe methods are not customer-creatable through this endpoint.** Stripe binding requires a Setup Intent flow (not yet exposed); for now, AuthPI staff provision Stripe methods directly via internal tooling. Sending a Stripe payload here returns `400`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | Account ID |

### Request body

Content type: `application/json`

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | x402 | Required |  |
| `label` | string | Optional |  |
| `allowed_payer_wallets` | string[] | Optional |  |
| `auto_topup_increment_μusd` | integer | Optional |  |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 201 | x402 payment method added | `object` |
| 400 | **Bad Request** - The request is malformed or contains invalid data. | `ApiError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## PATCH /v1/accounts/{account_id}/payment-methods/{method_id}

**Update Account Payment Method**

Update mutable fields on a payment method (label, enabled state, x402 batching/restrictions). Disabling a method starts a 15-second grace window during which in-flight settlements still complete.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | Account ID |
| `method_id` | string | Required | Payment Method ID |

### Request body

Content type: `application/json`

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | string \| null | Optional |  |
| `enabled` | boolean | Optional |  |
| `allowed_payer_wallets` | array \| null | Optional |  |
| `auto_topup_increment_μusd` | integer \| null | Optional |  |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Payment method updated | `object` |
| 400 | **Bad Request** - The request is malformed or contains invalid data. | `ApiError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## DELETE /v1/accounts/{account_id}/payment-methods/{method_id}

**Remove Account Payment Method**

Soft-remove a payment method. Terminal — the method is retained in the list for audit but no longer accepted for settlements.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | Account ID |
| `method_id` | string | Required | Payment Method ID |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 204 | Payment method removed | — |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |