Console and admin API

Every endpoint of the customer console API (/v1/account, /v1/console) and the private operator admin API (/v1/admin), with their OpenAPI contracts.

Everything the console at /app does goes through a JSON API you can call yourself. The contracts are OpenAPI 3.1 documents, checked by the test suite against the registered routes and real responses:

• /docs/openapi-console.yaml: the account and console API, for customers;
• /docs/openapi-admin.yaml: the operator admin API.

Errors are {"error": "<code>", "message": "…"}; the codes are on Error codes.

Authentication

• Console. POST /v1/account/login sets the ag_account session cookie (HttpOnly, SameSite=Lax, Secure over TLS; 12 hours, or 2 hours without use). GET /v1/account/session returns the signed-in user, the customer and a CSRF token; send it as X-CSRF-Token on every request that changes something. Requests from other sites are refused (cross_origin).
• Two-factor authentication. With 2FA on, login answers {"mfaRequired": true} and a 5-minute pre-session; POST /v1/account/login/mfa with the code from the authenticator app (or a recovery code) completes the sign-in. An account can require 2FA of all its members; members without it get 403 mfa_setup_required on the console until they turn it on.
• API tokens. For scripts and CI, create a token under API tokens and send Authorization: Bearer agt_… to /v1/console/* (no CSRF token). A token is limited to its scopes (sites:read, sites:write, analytics:read, members:read) and never works on /v1/account or /v1/admin.
• Admin. The admin API is private: the public host answers 404 for /v1/admin/. Operators reach it on a private network or through an SSH tunnel, sign in with the operator key (POST /v1/admin/login, cookie ag_admin) and send X-CSRF-Token on changes.
• Operator and customer sessions never unlock each other's APIs. A customer sees only its own sites; another customer's site key answers 404.
• Accounts and roles. A user can belong to several accounts; the session works in one at a time (the active account, changed with POST /v1/account/switch). In each account the user has a role: owner, admin, member or readonly. Every console route needs a permission of that role: sites:read, sites:write, analytics:read, members:read, members:write, tokens:write, account:write, account:delete or audit:read. A missing one answers 403 forbidden and names it. A suspended account answers 403 account_suspended (its sites keep protecting), a suspended user 403 user_suspended.

Account

Console

Limits are per account: by default 5 sites, 3 live backend secrets per site, 10 members and 25 live API tokens (GET /v1/console/account shows them and the usage). New sites start in monitor mode with one browser-checked action, submit.

Admin (private)

Public endpoints

These need no session; they are documented on their own pages.