Log in with email and password

Authenticates an identity using an email address and password. On success this creates either a fully active session or a pending-MFA session, depending on whether the identity has any active multi-factor authentication methods enrolled.

This endpoint is intentionally unauthenticated (no Authorization header is required or checked) since it is the entry point used to obtain a session.

Before validating credentials, the request is checked against per-IP and per-account failed-login-attempt windows and against the IP blocklist:

If the originating IP address has recorded MAX_LOGIN_ATTEMPTS (default 5) failed attempts within the trailing LOGIN_LOCK_WINDOW_MS window (default 15 minutes), the request is rejected before the account is even looked up.

If the IP address is on the blocklist, the request is rejected immediately.

Once the account is identified, the same failed-attempt threshold is enforced per-account within the same trailing window.

Every attempt (matched account or not) is recorded for attempt-tracking purposes; a failed attempt against an unknown email is recorded against the IP only, while a failed attempt against a known email is recorded against both the IP and the account.

The identity's email-password auth method must exist, be in active status, and have been verified (verified_at set) before a password check is performed. The parent identity must not be disabled or suspended.

If the credentials are valid and the identity has one or more active MFA methods enrolled, a pending-mfa session is created (short-lived, expiring after MFA_PENDING_SESSION_EXPIRES_IN_MS, default 5 minutes) and the response indicates mfa_required: true along with the available next steps for completing MFA. If the identity has no active MFA methods, a normal active session is created immediately and mfa_required: false is returned along with the full session token and identity summary.

application/json

Authentication succeeded. Either a pending-MFA session or a fully active session was created, depending on whether the identity has active MFA methods enrolled.

Bodyapplication/json

{ "message": "Success", "status": "success", "data": { "mfa_required": false, "session_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uX2lkIjoiMDFIWDhYS1haUFlTVkFFOEhIWlhNVFpGUlIifQ.abc123", "session_id": "01HX8XKXZPYSVAE8HHZXMTZFRR", "identity_id": "01HX8XKXZPYSVAE8HHZXMTZFAA", "expires_at": 1754560800000, "identity": { "name": "Jane Doe", "primary_email": "jane.doe@example.com", "status": "active" } } }

Log in with email and password

Request

Responses