Authentication API

Checks whether an email address is already registered within a given tenant. This public endpoint allows onboarding and login workflows to validate email availability before submission. Includes per-IP rate limiting and bot protection.

{
  "tenant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "email": "jane@acme-corp.com",
  "captcha_token": "0.AbCdEf123..."
}

Creates a new user within a tenant. Validates the password against the tenant's password policy, sends a verification email, and returns tokens so the user is authenticated immediately.

{
  "email": "jane@acme-corp.com",
  "password": "SecureP@ss2024!",
  "display_name": "Jane Smith",
  "tenant_id": "tnt_01H7ABCD9E8F4G2H1J3K5L7M"
}

Authenticates a user with email and password. Returns tokens on success, or indicates that MFA verification or a risk challenge is required. The risk engine evaluates every login attempt automatically.

{
  "email": "jane@acme-corp.com",
  "password": "SecureP@ss2024!",
  "tenant_id": "tnt_01H7ABCD9E8F4G2H1J3K5L7M"
}

Completes authentication when MFA is required. Submit the TOTP code from the user's authenticator app along with the mfa_token received from the login response. The MFA token is valid for 5 minutes.

{
  "mfa_token": "mfa_01H8NXYZ...",
  "code": "482913"
}

Exchanges a valid refresh token for a new access token and refresh token pair. Refresh tokens are single-use — the old token is invalidated immediately (rotation). If a refresh token is used twice, the entire session is revoked.

{
  "refresh_token": "ref_01H8MWXY7A9B3C5D..."
}

Revokes the current session and invalidates the refresh token. The access token will remain valid until it expires (max 15 minutes), so for immediate revocation, also remove the token from your client storage.

Changes the authenticated user's password. Requires the current password for verification. The new password is validated against the tenant's password policy. All other sessions for this user are revoked on success.

{
  "current_password": "SecureP@ss2024!",
  "new_password": "EvenStr0nger#2025"
}

Initiates the password reset flow by sending a reset link to the user's email. Always returns 200 regardless of whether the email exists (prevents user enumeration). The reset token is valid for 1 hour.

{
  "email": "jane@acme-corp.com",
  "tenant_id": "tnt_01H7ABCD9E8F4G2H1J3K5L7M"
}

Completes the password reset using the token from the email link. Validates the new password against the tenant's policy and revokes all existing sessions for the user.

{
  "token": "rst_01H8QWER5T7Y9U1I...",
  "new_password": "MyNewSecure#Pass1"
}

Confirms the user's email address using the token from the verification email sent during registration. The token is valid for 24 hours.

{
  "token": "evf_01H8ASDF3G5H7J9K..."
}

Sends a new email verification link if the original expired. Rate-limited to 3 requests per hour per user. Returns 200 regardless of whether the email exists.

{
  "email": "jane@acme-corp.com",
  "tenant_id": "tnt_01H7ABCD9E8F4G2H1J3K5L7M"
}

What's Next