AINode Tenant Administration API
The AINode theme registers the tenant administration page at /admin/extensions/tenants. All browser calls use the existing APay proxy at /api/proxy/external with a fixed page-owned path=/api/admin/tenants..., matching the AINode customer-management pages. The browser never receives the upstream credential.
The proxy requires an APay administrator session whenever the resolved upstream path is /api/admin or starts with /api/admin/; a normal user session or x-auth value cannot use the AINode admin credential. It uses the existing APay integration_token setting, falling back to NUXT_SESSION_PASSWORD, and the selected value must equal AINode's internal.token. A newly created tenant's integrationToken cannot authorize AINode admin endpoints.
Endpoints
GET /api/proxy/external?path=/api/admin/tenants
Lists tenants with their name, code, status, direct-login setting, API Key group keyGroupId/keyGroupName, wallet count, creation time, funding mode, wholesale-rate snapshot, and deposit balance. The page also calls GET /api/proxy/external?path=/api/admin/key-groups for the selectable groups; tenants can only be assigned to groups in that response.
POST /api/proxy/external?path=/api/admin/tenants
Creates a tenant. The body accepts name, code, allowDirectLogin, and keyGroupId. The code is normalized to lowercase, must match ^[a-z0-9][a-z0-9_-]{1,62}$, and cannot be default. keyGroupId must be a positive ID from the current group list, while 0 creates the tenant without a group.
The response contains an integrationToken only at creation time. The admin page keeps it in memory and clears it when the result dialog closes; it is not written to local storage, cookies, APay's database, or application logs. The request is sent with automatic retries disabled.
PUT /api/proxy/external?path=/api/admin/tenants/{id}
Changes a tenant's API Key group. AINode's tenant update is not a partial PATCH, so the body must carry the latest list snapshot of all required fields: name, code, status, allowDirectLogin, and the new keyGroupId. keyGroupId=0 removes the current group association. APay rebuilds the allowed body and rejects extra fields, invalid statuses, invalid tenant IDs, or negative group IDs; the page only allows IDs from the current group list.
POST /api/proxy/external?path=/api/admin/tenants/{id}/rotate-token
Rotates the tenant integrationToken. AINode stores only the token's SHA-256 hash, so an existing token cannot be retrieved. A successful rotation invalidates the old token immediately. The new integrationToken is shown once and cleared from page memory when the result dialog closes.
Rotation disables automatic retries and has no idempotency key. If the HTTP request times out or loses its response, the old token may already be invalid while the operator never received the new token. The page reports an uncertain result and neither assumes success nor rotates again automatically. Check the consumer's access before deciding whether to perform another rotation.
GET /api/proxy/external?path=/api/admin/tenants/{id}/deposit
Returns the current funding configuration and deposit balance together with ledger aggregates: paid top-ups, grants, opening-balance entries, net admin adjustments, applied issuance, issuance face amount, shadow issuance, and a ledger-derived balance. ledger.balanced is true only when the independently derived balance equals the stored deposit balance.
POST /api/proxy/external?path=/api/admin/tenants/{id}/deposit
Credits a tenant deposit. This APay endpoint intentionally supports only positive credits and these entry types:
deposit_topup: paid funding;deposit_grant: grant or rebate;opening_balance: historical opening-balance entry;admin_adjust: positive administrative correction.
The body contains amount as a positive decimal string with at most eight decimal places, a required remark of at most 1,000 characters, type, and a UUID requestId. APay maps the UUID to apay-tenant-deposit:{tenantId}:{requestId} and sends it as AINode's eventId. AINode updates the balance and inserts the ledger row in one database transaction; its unique event-ID index rejects a replay.
The browser disables automatic retries and retains the same request ID after an error or timeout. When the result is uncertain, refresh the balance and ledger before retrying. A successful operation clears the form and generates a new request ID. Debit adjustments, refunds, funding-mode edits, discount changes, exemptions, and tenant deletion are not exposed by this API.
GET /api/proxy/external?path=/api/admin/tenants/{id}/ledger&limit=50&offset=0
Returns ledger rows newest first. limit must be between 1 and 200; the admin page loads 50 rows at a time. Each row can include type, direction, face and charged amounts, the wholesale-rate snapshot, whether the entry affected the deposit, balances before and after, balance type, linked user/wallet/transaction IDs, event ID, remark, and creation time.
AINode currently returns no total count and provides no server-side filtering or export. The proxy forwards the authenticated APay admin ID and AINode stores it as operator_admin_id, but the current ledger response exposes neither that field nor metadata. Because this call uses /api/proxy/external rather than an APay /api/admin/** route, it is not covered by APay's admin operation-log plugin. Remarks, event IDs, and linked transaction IDs are therefore the visible evidence until AINode exposes the stored operator or APay adds dedicated proxy auditing.
Amount and ID precision
AINode stores USD amounts as signed integers scaled by 10^8. APay quotes scaled amount fields and 64-bit ledger/transaction IDs before JSON parsing, then keeps them as strings in the browser. Display conversion uses integer arithmetic and shows up to eight decimal places, preventing JavaScript Number precision loss.
Tenant IDs are positive 32-bit integers. The page sends bounded ledger limit and offset values through the proxy.
Reconciliation and rollback boundary
AINode's deposit write and ledger insert commit together, so a rejected or rolled-back request changes neither. A lost HTTP response can still follow a successful commit, which is why a retry must reuse the original request ID and operators must inspect the balance and ledger first. A balanced: false result indicates an out-of-ledger balance change or another accounting inconsistency; stop funding and investigate instead of correcting it blindly through another top-up.