Authentication
Login, registration, token issuance and session management.
📄️ Login User
Authenticate a user with email (username optional) and password and return a bearer token. When the user has 2FA enabled, a 2FA-required response is returned instead and the login must be completed via the 2FA verification endpoint. Responds 401 for wrong credentials; rate-limited to 10 requests per minute.
📄️ Read User Session
Return the authenticated user's profile and session data, including the client's configured remediation language. Responds 401 for an invalid or expired token and 404 when the user or client no longer exists.
📄️ Logout User
Revoke the current user's session token and reset the client's OAuth provider state. Requires a valid bearer token; responds 401 when the token is invalid or already expired.
📄️ Register User
Register a new user with email and password (no OAuth) and send a verification email. Re-registering an unverified email resends the verification, rate-limited to 3 resends per hour. Responds 409 when the email is already registered and verified; registration is also subject to geo-location restrictions.
📄️ Request GitHub OAuth URL
Build and return the GitHub OAuth authorization URL, using the configured client credentials and frontend callback, to which the browser should be redirected for authentication. `mode` selects the contract the callback will run: `register` (the default) registers or logs in, `login` never creates a user. Pass `verification_token` to start an invited account's setup instead: the returned URL carries a signed state bound to that token, and the callback only completes setup when GitHub's verified email matches the invited account's. `binding` (required) is the lowercase hex sha256 of the nonce the frontend start route keeps in a cookie on the starting browser; the signed state carries it and the callback refuses any other browser.
📄️ Exchange Web-Session JWT for CLI API Token
Called by the frontend /auth/cli page after the user authorizes the CLI. Mints a new CLI-named API token (90-day TTL), records it in the audit log and returns {token, email}. Only a signed-in web session may call it (an API token is refused with 403). Rate-limited to 5 exchanges per 60 seconds per IP and 10 token creations per hour per user (shared with POST /users/me/api-tokens). DEPRECATED (old TUIs only): answers with a Deprecation header while the CLI_LEGACY_EXCHANGE flag is on, and 410 upgrade_required (nothing minted) when off.
📄️ Authorize a Plexicus client (loopback + PKCE)
Called by the /auth/cli consent page after the signed-in user clicks Authorize. Body: client_id (plexicus-tui|plexicus-mcp|plexicus-cli), code_challenge (S256), state, redirect_port (9100-9199 on 127.0.0.1), device_name, scope, ttl_days. Returns the loopback redirect URL that carries a 60-second single-use code and the state, never a token. Needs a web session (API tokens get 403).
📄️ Exchange a loopback code + PKCE verifier for a client token
Body (JSON or form): code, code_verifier, client_id, redirect_uri, optional state. Returns the personal API token (90-day default, 365 max) once. A wrong verifier, a reused or expired code, another client or redirect: 400 invalid_grant, and the code is burned. No authentication header; rate limited per IP.
📄️ Client login configuration for the /auth/cli page
Public, no secrets: tells the consent page whether the legacy token-in-URL exchange (old TUIs, CLI_LEGACY_EXCHANGE) is still accepted, so it can refuse a request without a code_challenge when it is not.
📄️ Start a device login (RFC 8628)
Body (form or JSON): client_id (plexicus-tui|plexicus-mcp|plexicus-cli), scope, device_name. Returns device_code, user_code (XXXX-XXXX), verification_uri, expires_in (600) and interval (5). No authentication; rate limited per IP.
📄️ Token endpoint (device code or loopback authorization code)
grant_type=urn:ietf:params:oauth:grant-type:device_code with device_code and client_id: 400 authorization_pending | slow_down | access_denied | expired_token, or 200 with the client token once. grant_type=authorization_code: same as POST /auth/cli/token. No authentication; rate limited per IP.
📄️ Show a pending device login for consent (/activate)
Body: user_code. Returns the client name, device and requested access of a pending device login so the signed-in user can approve or deny it. 404 invalid_user_code for an unknown, used or expired code. Web session only; brute-force limited per user, per IP and per code (429 for 15 minutes).
📄️ Approve or deny a pending device login (/activate)
Body: user_code, approve (true|false), optional ttl_days (1-365, default 90). Approving binds the device login to the signed-in user; the polling client then receives its token once. Web session only (API tokens get 403); same brute-force limits as the lookup; approvals count toward the 10 tokens/hour/user budget.
📄️ Request Password Reset
Send a password reset link to the given email address when it matches an account. Always returns a generic success message so account existence is not disclosed. The reset token expires after 15 minutes.
📄️ Confirm Password Reset
Set a new password using a reset token previously delivered by email. Returns 401 when the token is invalid or has expired.