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.

📄️ 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 and returns {token, email}. Rate-limited to 5 exchanges per 60 seconds per IP.

📄️ 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.