Multi-Factor Authentication
AuthProxy supports multiple authentication methods that can work together to provide layered security. The full catalogue is exposed at /auth/v1/get_info so PWA frontends know which login forms to render.
Authentication methods at a glance
| Layer | Method | Endpoint | Notes |
|---|---|---|---|
| Primary | FIDO2 / WebAuthn | POST /auth/v1/login + /auth/v1/keys/* | Hardware key challenge-response. Up to ActiveKeysLimit (default 5) per user. |
| Primary | Ed25519 passkey | POST /auth/v1/login | Challenge-response over Ed25519. Required for browser sessions on production stands. |
| Primary | Magic link / Email OTP | POST /auth/v1/login_email + GET /auth/v1/magic?token=… | Email-only login; verifies the email contact when used (see Verified Contacts). |
| Primary | Phone OTP | POST /auth/v1/login_phone | Phone-only login; SMS code with retry policy. |
| Primary | OAuth providers | GET /auth/v1/social/{google,github,facebook,vk,discord,telegram} + POST /auth/v1/social/apple | Per-provider configuration; social flow may return Success, LinkConfirmationRequired, or ManualLinkRequired. |
| Primary | Federation v2 | /auth/v1/federated/{providers,start,login} | Login through a verified partner ItBuild project. |
| Primary | MCP | POST /auth/v1/mcp_login | Programmatic only — not a browser session. |
| Second factor | Same key signature on sensitive actions | Header X-Signature + X-SignResult injection | TrexWallet, internal transfer, withdraw. |
Each method maps to a LoginMethod enum value and is recorded in login_log with the resulting crm_id. Settings in /ProxyAdmin/Settings toggle per-method login and registration independently — for example, you can allow OAuth login but block first-time registration through it.
Layering and login forms
AuthProxy ships several login forms (Form0 … FormN) that can be combined per project:
Form0— federation provider picker (rendered when at least one federated provider is enabled, see Federation v2 — Browser Login).Form1— passkey / FIDO2 challenge form (default for production).- Other forms — magic-link email, phone OTP, password (if explicitly enabled), and so on.
Operators choose which form is the default at /ProxyAdmin/AuthMethods and which fall-backs the PWA may offer.
Always-available methods
Passkey / Ed25519 user keys and FIDO2 are always available for login — the key-based login path does not consult EnabledLoginMethods, so it cannot be disabled through the admin panel. This guarantees that operators can always sign in even if every OAuth and OTP path is misconfigured.
Note: creating a new account with a given method is governed separately by
AccountCreationLoginMethods. "Always available" applies to authenticating an existing key, not to self-service account creation.
Sensitive operations and signatures
After login, sensitive operations (TrexWallet internal_transfer, create_swap, withdraw, etc.) can demand an additional Ed25519 signature on the request body. AuthProxy validates the signature against the user's registered key and forwards the result to the backing module as X-SignResult: valid. The module then enforces the Require2FA flag on the user / wallet to decide whether to proceed.
Key management
| Endpoint | Purpose |
|---|---|
POST /auth/v1/keys/register_key | Register a new FIDO2 hardware key or an Ed25519 software passkey (selected by the AuthIn payload). |
GET /auth/v1/keys/user_keys | List the current user's active keys. |
POST /auth/v1/keys/remove_key | Soft-delete a key by keyId (last active key still has to remain reachable through some method). |
POST /auth/v1/keys/update_key | Toggle mcpAccess and cardDavAccess on an existing key. |
Operator-side cross-user listing lives in the admin panel (/ProxyAdmin/UserKeys), not on the public API.
For the full request/response shape see the built-in Swagger UI at /docs/swagger/ and Authentication API.