Account management endpoints. An Account is your billing and administrative entity in AuthPI—it contains Issuers, manages billing, and holds administrative memberships.
Base URL: https://api.authpi.com — see the Core API overview for
authentication, pagination, and idempotency, or try these endpoints in the
interactive reference.
GET/v1/accountsList Accounts
List all accounts the authenticated user has access to
| Name | Type | Required | Description |
|---|---|---|---|
limit | integer | Optional | |
cursor | string | Optional |
| 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
| Name | Type | Required | Description |
|---|---|---|---|
account_id | string | Required | Account ID |
| 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
| Name | Type | Required | Description |
|---|---|---|---|
account_id | string | Required | Account ID |
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 |
| 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/ledgerList Account Credit Ledger
List account credit ledger entries, most recent first
| Name | Type | Required | Description |
|---|---|---|---|
account_id | string | Required | Account ID |
| Name | Type | Required | Description |
|---|---|---|---|
limit | integer | Optional | |
cursor | string | Optional |
| 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/topupsCreate Account Credit Top-up
Settle an x402 payment and add prepaid credits to the account
| Name | Type | Required | Description |
|---|---|---|---|
account_id | string | Required | Account ID |
Content type: application/json
| Property | Type | Required | Description |
|---|---|---|---|
amount_μusd | integer | Required |
| 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-methodsAdd 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.
| Name | Type | Required | Description |
|---|---|---|---|
account_id | string | Required | Account ID |
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 |
| 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.
| Name | Type | Required | Description |
|---|---|---|---|
account_id | string | Required | Account ID |
method_id | string | Required | Payment Method ID |
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 |
| 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.
| Name | Type | Required | Description |
|---|---|---|---|
account_id | string | Required | Account ID |
method_id | string | Required | Payment Method ID |
| 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 |