Authentication - LibreChat

Overview

LibreChat supports two authentication methods:

JWT Authentication: Session-based authentication for web applications
API Keys: Token-based authentication for programmatic access

JWT Authentication

JWT (JSON Web Token) authentication is the primary method for web applications. Obtain a JWT token by authenticating with credentials:

POST /api/auth/login
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "your-password"
}

Request Body

string

required

User’s email address

password

string

required

User’s password

Response

token

string

JWT access token

user

object

User information including id, email, name, and role

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "user123",
    "email": "[email protected]",
    "name": "John Doe",
    "role": "user"
  }
}

Using JWT Tokens

Include the JWT token in the Authorization header:

GET /api/convos
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Refresh Token

Refresh an expired JWT token:

POST /api/auth/refresh

retry

boolean

Set to true to retry refresh

Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": { ... }
}

Logout

Invalidate the current session:

POST /api/auth/logout
Authorization: Bearer <token>

Registration

Create a new user account:

POST /api/auth/register
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "secure-password",
  "name": "John Doe",
  "username": "johndoe"
}

Request Body

string

required

User’s email address (must be unique)

password

string

required

Password (minimum 8 characters)

name

string

required

User’s full name

username

string

Username (optional)

confirm_password

string

Password confirmation (if required by server configuration)

Password Reset

Request Password Reset

Send a password reset email:

POST /api/auth/requestPasswordReset
Content-Type: application/json

{
  "email": "[email protected]"
}

string

required

Email address of the account to reset

Reset Password

Reset password with token from email:

POST /api/auth/resetPassword
Content-Type: application/json

{
  "userId": "user123",
  "token": "reset-token-from-email",
  "password": "new-secure-password"
}

userId

string

required

User ID from reset email

token

string

required

Reset token from email

password

string

required

New password

Two-Factor Authentication (2FA)

Enable 2FA

Enable two-factor authentication for your account:

GET /api/auth/2fa/enable
Authorization: Bearer <token>

Response

qrCode

string

QR code data URL for authenticator app

secret

string

TOTP secret for manual entry

backupCodes

string[]

One-time backup codes for account recovery

{
  "qrCode": "data:image/png;base64,...",
  "secret": "JBSWY3DPEHPK3PXP",
  "backupCodes": [
    "12345678",
    "87654321",
    "..."
  ]
}

Verify 2FA Code

Verify a TOTP code from authenticator app:

POST /api/auth/2fa/verify
Authorization: Bearer <token>
Content-Type: application/json

{
  "token": "123456"
}

token

string

required

6-digit TOTP code from authenticator app

Confirm 2FA Setup

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"
}

Regenerate Backup Codes

Generate new backup codes:

POST /api/auth/2fa/backup/regenerate
Authorization: Bearer <token>

Verify with Temp Token

Verify 2FA during login flow:

POST /api/auth/2fa/verify-temp
Content-Type: application/json

{
  "tempToken": "temp-token-from-login",
  "token": "123456"
}

tempToken

string

required

Temporary token received during login

token

string

required

6-digit TOTP code or backup code

API Keys

API keys provide programmatic access to LibreChat for agents and integrations.

Create API Key

Create a new API key for agent access:

POST /api/api-keys
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "My Integration",
  "expiresAt": "2024-12-31T23:59:59Z"
}

name

string

required

Descriptive name for the API key

expiresAt

string

ISO 8601 expiration date (optional)

Response

key

string

The API key (only shown once)

string

Unique identifier for this key

name

string

Name of the API key

createdAt

string

Creation timestamp

{
  "key": "lc_ak_1234567890abcdef",
  "id": "key123",
  "name": "My Integration",
  "createdAt": "2024-01-01T00:00:00Z",
  "expiresAt": "2024-12-31T23:59:59Z"
}

List API Keys

Retrieve all API keys for your account:

GET /api/api-keys
Authorization: Bearer <token>

Response

[
  {
    "id": "key123",
    "name": "My Integration",
    "createdAt": "2024-01-01T00:00:00Z",
    "expiresAt": "2024-12-31T23:59:59Z",
    "lastUsedAt": "2024-03-01T12:00:00Z"
  }
]

Get API Key

Retrieve details of a specific API key:

GET /api/api-keys/:id
Authorization: Bearer <token>

string

required

API key ID

Delete API Key

Revoke an API key:

DELETE /api/api-keys/:id
Authorization: Bearer <token>

string

required

API key ID to delete

Using API Keys

Include the API key in the Authorization header:

GET /api/agents/v1/chat/completions
Authorization: Bearer lc_ak_1234567890abcdef

LibreChat supports OAuth authentication providers:

Google OAuth

Initiate Google OAuth flow:

GET /api/auth/google

Redirects to Google OAuth consent screen.

Facebook OAuth

Initiate Facebook OAuth flow:

GET /api/auth/facebook

Graph Token (Microsoft)

Obtain Microsoft Graph API token:

GET /api/auth/graph-token?scopes=Files.Read
Authorization: Bearer <token>

scopes

string

required

Space-separated Microsoft Graph scopes

Response

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGci...",
  "expires_in": 3600
}

Security Best Practices

Never share your JWT tokens or API keys
Use HTTPS in production to prevent token interception
Rotate API keys regularly
Enable 2FA for additional account security
Set API key expiration dates for temporary integrations
Store tokens securely (use httpOnly cookies for web apps)
Validate all inputs on the client side before sending

Error Responses

Invalid Credentials

{
  "error": "Invalid credentials",
  "message": "Email or password is incorrect"
}

Token Expired

{
  "error": "Token expired",
  "message": "Your session has expired. Please log in again."
}

Rate Limited

{
  "error": "Too many requests",
  "message": "Too many login attempts. Please try again later."
}

Overview

Endpoints

Integration

​Overview

​JWT Authentication

​Login

​Request Body

​Response

​Using JWT Tokens

​Refresh Token

​Response

​Logout

​Registration

​Request Body

​Password Reset

​Request Password Reset

​Reset Password

​Two-Factor Authentication (2FA)

​Enable 2FA

​Response

​Verify 2FA Code

​Confirm 2FA Setup

​Disable 2FA

​Regenerate Backup Codes

​Verify with Temp Token

​API Keys

​Create API Key

​Response

​List API Keys

​Response

​Get API Key

​Delete API Key

​Using API Keys

​OAuth / Social Login

​Google OAuth

​Facebook OAuth

​Graph Token (Microsoft)

​Response

​Security Best Practices

​Error Responses

​Invalid Credentials

​Token Expired

​Rate Limited

Build docs developers (and LLMs) love

Overview

JWT Authentication

Login

Request Body

Response

Using JWT Tokens

Refresh Token

Response

Logout

Registration

Request Body

Password Reset

Request Password Reset

Reset Password

Two-Factor Authentication (2FA)

Enable 2FA

Response

Verify 2FA Code

Confirm 2FA Setup

Disable 2FA

Regenerate Backup Codes

Verify with Temp Token

API Keys

Create API Key

Response

List API Keys

Response

Get API Key

Delete API Key

Using API Keys

OAuth / Social Login

Google OAuth

Facebook OAuth

Graph Token (Microsoft)

Response

Security Best Practices

Error Responses

Invalid Credentials

Token Expired

Rate Limited