Overview
Authentication endpoints handle user login, registration, password reset, and two-factor authentication.
All auth endpoints are prefixed with /api/auth.
Login
Authenticate and obtain a JWT token:
POST /api/auth/login
Content-Type: application/json
{
"email": "[email protected]",
"password": "your-password"
}
Request Body
Response
User object with profile information
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": {
"id": "user123",
"email": "[email protected]",
"name": "John Doe",
"role": "user"
}
}
{
"tempToken": "temp_abc123",
"message": "2FA verification required"
}
Logout
Invalidate the current session:
POST /api/auth/logout
Authorization: Bearer <token>
Response
{
"message": "Logged out successfully"
}
Register
Create a new user account:
POST /api/auth/register
Content-Type: application/json
{
"email": "[email protected]",
"password": "secure-password",
"name": "Jane Smith",
"username": "janesmith"
}
Request Body
Email address (must be unique)
Password (minimum 8 characters)
Password confirmation (if required by server)
Response
Returns the same format as login (token + user object).
Note: Registration may require:
- Invitation codes (if server is invite-only)
- Email verification before account activation
- Agreement to terms of service
Refresh Token
Refresh an expired or expiring JWT token:
Query Parameters
Set to true to retry refresh
Response
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": {...}
}
Password Reset
Request Password Reset
Send a password reset email:
POST /api/auth/requestPasswordReset
Content-Type: application/json
{
"email": "[email protected]"
}
Email address of the account
Response
{
"message": "Password reset email sent"
}
Reset Password
Reset password using token from email:
POST /api/auth/resetPassword
Content-Type: application/json
{
"userId": "user123",
"token": "reset-token-from-email",
"password": "new-secure-password"
}
Response
{
"message": "Password reset successful"
}
Two-Factor Authentication
Enable 2FA
Enable two-factor authentication:
GET /api/auth/2fa/enable
Authorization: Bearer <token>
Response
QR code data URL for authenticator app
TOTP secret for manual entry
{
"qrCode": "data:image/png;base64,iVBORw0KG...",
"secret": "JBSWY3DPEHPK3PXP",
"backupCodes": [
"12345678",
"87654321",
"11223344",
"55667788",
"99001122"
]
}
Verify 2FA Code
Verify a TOTP code:
POST /api/auth/2fa/verify
Authorization: Bearer <token>
Content-Type: application/json
{
"token": "123456"
}
6-digit TOTP code from authenticator app
Confirm 2FA
Confirm and activate 2FA:
POST /api/auth/2fa/confirm
Authorization: Bearer <token>
Content-Type: application/json
{
"token": "123456"
}
Disable 2FA
Disable two-factor authentication:
POST /api/auth/2fa/disable
Authorization: Bearer <token>
Content-Type: application/json
{
"token": "123456"
}
6-digit TOTP code to confirm disable
Regenerate Backup Codes
Generate new backup codes:
POST /api/auth/2fa/backup/regenerate
Authorization: Bearer <token>
Response
{
"backupCodes": [
"12345678",
"87654321",
"11223344"
]
}
Verify with Temp Token
Complete 2FA verification during login:
POST /api/auth/2fa/verify-temp
Content-Type: application/json
{
"tempToken": "temp_abc123",
"token": "123456"
}
Temporary token from login response
6-digit TOTP code or backup code
Response
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": {...}
}
OAuth / Social Login
Google OAuth
Initiate Google OAuth flow:
Redirects to Google OAuth consent screen. After authentication, redirects back to LibreChat with auth token.
Facebook OAuth
Initiate Facebook OAuth flow:
Graph Token (Microsoft)
Obtain Microsoft Graph API token:
GET /api/auth/graph-token?scopes=Files.Read%20User.Read
Authorization: Bearer <token>
Query Parameters
Space-separated Microsoft Graph scopes (URL-encoded)
Response
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGci...",
"token_type": "Bearer",
"expires_in": 3600
}
LDAP Authentication
If LDAP is configured (LDAP_URL and LDAP_USER_SEARCH_BASE environment variables), the login endpoint will authenticate against LDAP instead of local database.
Error Responses
Invalid Credentials
{
"error": "Invalid credentials",
"message": "Email or password is incorrect"
}
Email Already Exists
{
"error": "Email already exists",
"message": "An account with this email already exists"
}
Weak Password
{
"error": "Weak password",
"message": "Password must be at least 8 characters"
}
Account Banned
{
"error": "Account banned",
"message": "Your account has been suspended"
}
Rate Limited
{
"error": "Too many requests",
"message": "Too many login attempts. Please try again later."
}
Invalid 2FA Token
{
"error": "Invalid 2FA token",
"message": "The verification code is incorrect"
}
Security Features
- Rate Limiting: Login and registration endpoints have strict rate limits
- Password Hashing: Passwords are hashed using bcrypt
- JWT Expiration: Tokens expire and require refresh
- HTTPS Required: Production deployments should use HTTPS
- CSRF Protection: Session cookies include CSRF tokens
- Account Lockout: Multiple failed login attempts may lock the account
- Email Verification: Optional email verification before account activation