Skip to main content

​
Session status

​
GET /api/auth

  • Auth – optional.
  • Response – { status: "ok" | "email_not_verified" | "2fa_required", auth } where auth echoes the JWT payload or null.
Use this endpoint to decide whether the user must verify email or pass 2FA before granting UI access.

​
Account lifecycle

EndpointPurposeBodyNotes
POST /api/auth/registerCreate an account.{ firstName, lastName, email, password, confirmPassword, remember }Returns { status: "email_not_verified", token? } and sets a cookie when remember is truthy.
POST /api/auth/loginIssue a new session.{ email, password, remember }Responses include { status, token? }. Cookies inherit the remember flag.
GET /api/auth/logoutDestroy the cookie.—Always returns { status: "logout" }.

​
Email verification

EndpointAuthBodyDescription
POST /api/auth/verify/requestSigned-in user{ returnUrl? }Sends a verification email. returnUrl is optional and injected into the template.
POST /api/auth/verify/submitNone{ token }Exchanges the emailed JWT for { status: "ok", token } and refreshes the cookie.

​
Password reset

EndpointAuthBodyDescription
POST /api/auth/reset/requestNone{ email, returnUrl? }Issues a reset email if the account exists.
POST /api/auth/reset/submitNone{ token, password, confirmPassword }Validates the token, updates the password, and logs the user in.

​
Two-factor authentication (TOTP)

All endpoints require an email-verified session.
  • POST /api/auth/2fa/enable/request → { status: "2fa_setup", url, secret }. url is a TOTP URI you can render as a QR code.
  • POST /api/auth/2fa/enable/submit with { token } confirms setup and issues a fresh cookie.
  • POST /api/auth/2fa/verify with { token } completes login when status === "2fa_required".
  • POST /api/auth/2fa/reset with { token } rotates the 2FA secret and re-enters the "2fa_setup" state.

​
External providers

EndpointDescription
GET /api/auth/external/providersLists configured providers from OPENID_PROVIDERS.
GET /api/auth/externalSigned-in view of linked accounts plus unsupported provider records.
GET /api/auth/external/{provider}Returns { status: "ok", account } for a specific provider.
DELETE /api/auth/external/{provider}Unlinks the provider for the current user.
GET /api/auth/external/{provider}/initRedirects to the provider’s authorization URL, persisting PKCE state in cookies.
GET /api/auth/external/{provider}/redirectHandles the provider callback. Depending on context it links the account, logs a user in, or issues a short-lived token for /api/auth/external/register/{token}.
POST /api/auth/external/register/{token}Completes sign-up for users coming from the external redirect but without an existing Browsary account.
All external flows set or clear the openid_code and openid_state cookies automatically. After a successful redirect, the user is taken to /dashboard unless you specify a different returnUrl inside your email templates.