Authentication

Open WebUI supports multiple authentication methods to secure API access. Choose the method that best fits your use case.

Authentication Methods

1. JWT Token Authentication

JSON Web Tokens (JWT) are the primary authentication method for user sessions. Tokens are obtained by signing in and included in the Authorization header.

Obtaining a JWT Token

curl -X POST http://localhost:8080/api/v1/auths/signin \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your_password"
  }'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_at": 1735689600,
  "id": "user-uuid",
  "email": "[email protected]",
  "name": "John Doe",
  "role": "user",
  "profile_image_url": "/api/v1/users/user-uuid/profile/image",
  "permissions": {}
}

string

required

User’s email address

password

string

required

User’s password

Using JWT Tokens

Include the token in the Authorization header with the Bearer scheme:

curl http://localhost:8080/api/v1/chats \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

JWT tokens are signed using the WEBUI_SECRET_KEY environment variable with the HS256 algorithm.

Token Expiration

Tokens expire based on the JWT_EXPIRES_IN configuration (default: -1 for no expiration):

-1: Never expires
0: Expires immediately (single use)
Duration string: 30m, 2h, 7d, 4w (minutes, hours, days, weeks)

Token Response Fields:

token

string

The JWT token string

token_type

string

Always “Bearer”

expires_at

integer

Unix timestamp when the token expires (null if never expires)

Token Revocation

Tokens can be revoked by signing out:

curl -X GET http://localhost:8080/api/v1/auths/signout \
  -H "Authorization: Bearer {token}"

Token revocation requires Redis. Revoked tokens are stored with TTL matching the token expiration.

2. API Key Authentication

API keys provide non-expiring authentication suitable for programmatic access and integrations.

Generating an API Key

Create an API key for your user account:

curl -X POST http://localhost:8080/api/v1/auths/api_key \
  -H "Authorization: Bearer {jwt_token}"

Response:

{
  "api_key": "sk-1234567890abcdef1234567890abcdef"
}

API keys are only shown once upon creation. Store them securely. If lost, delete and create a new key.

Using API Keys

API keys use the same Authorization header format as JWT tokens:

curl http://localhost:8080/api/v1/models \
  -H "Authorization: Bearer sk-1234567890abcdef1234567890abcdef"

API keys are prefixed with sk- to distinguish them from JWT tokens.

API Key Requirements

API keys must be enabled globally: ENABLE_API_KEYS=true
Users need the features.api_keys permission (admins have this by default)
Each user can have one active API key at a time

Retrieving Your API Key

Get your current API key:

curl http://localhost:8080/api/v1/auths/api_key \
  -H "Authorization: Bearer {jwt_token}"

Deleting an API Key

Revoke your API key:

curl -X DELETE http://localhost:8080/api/v1/auths/api_key \
  -H "Authorization: Bearer {jwt_token}"

API Key Endpoint Restrictions

Administrators can restrict API keys to specific endpoints:

# Environment configuration
ENABLE_API_KEYS_ENDPOINT_RESTRICTIONS=true
API_KEYS_ALLOWED_ENDPOINTS=/api/v1/chat,/api/v1/models,/api/v1/generate

When restrictions are enabled:

JWT tokens have full access to all endpoints
API keys can only access whitelisted endpoints
Attempting to access a restricted endpoint returns 403 Forbidden

3. OAuth 2.0 / OpenID Connect

Open WebUI supports OAuth 2.0 and OpenID Connect for SSO with external providers.

Supported Providers

Google
Microsoft Azure AD
GitHub
Generic OpenID Connect providers
Custom OAuth providers

OAuth Configuration

Configure OAuth providers via environment variables or the admin panel:

OAUTH_PROVIDERS = {
  "google": {
    "client_id": "your-client-id.apps.googleusercontent.com",
    "client_secret": "your-client-secret",
    "server_metadata_url": "https://accounts.google.com/.well-known/openid-configuration",
    "scope": "openid email profile"
  }
}

OAuth Flow

Redirect user to /oauth/{provider}/login
User authenticates with the provider
Provider redirects to callback URL with authorization code
Open WebUI exchanges code for tokens
User is authenticated and receives a JWT token

OAuth Claims Mapping

Customize how user data is extracted from OAuth tokens:

OAUTH_EMAIL_CLAIM

string

default:"email"

Claim containing the user’s email address

OAUTH_USERNAME_CLAIM

string

default:"name"

Claim containing the user’s display name

OAUTH_PICTURE_CLAIM

string

default:"picture"

Claim containing the user’s profile image URL

Role-Based Access with OAuth

Map OAuth roles to Open WebUI roles:

ENABLE_OAUTH_ROLE_MANAGEMENT=true
OAUTH_ROLES_CLAIM=roles
OAUTH_ALLOWED_ROLES=user,admin,developer
OAUTH_ADMIN_ROLES=admin,super_admin

Users with roles in OAUTH_ADMIN_ROLES become admins
Users must have a role in OAUTH_ALLOWED_ROLES to access the system
Users without allowed roles are denied access

Account Merging

Merge OAuth accounts with existing email accounts:

OAUTH_MERGE_ACCOUNTS_BY_EMAIL=true

When enabled, signing in with OAuth links to existing accounts with matching email addresses.

Token Exchange (Advanced)

Exchange OAuth access tokens for Open WebUI JWT tokens:

ENABLE_OAUTH_TOKEN_EXCHANGE=true

curl -X POST http://localhost:8080/api/v1/auths/oauth/google/token/exchange \
  -H "Content-Type: application/json" \
  -d '{
    "token": "{oauth_access_token}"
  }'

Token exchange is disabled by default. Enable only when needed for external integrations.

4. LDAP Authentication

Authenticate users against LDAP/Active Directory servers.

LDAP Configuration

Configure LDAP via environment variables or admin panel:

ENABLE_LDAP=true
LDAP_SERVER_HOST=ldap.example.com
LDAP_SERVER_PORT=389
LDAP_SEARCH_BASE=dc=example,dc=com
LDAP_APP_DN=cn=admin,dc=example,dc=com
LDAP_APP_PASSWORD=admin_password
LDAP_ATTRIBUTE_FOR_MAIL=mail
LDAP_ATTRIBUTE_FOR_USERNAME=uid
LDAP_USE_TLS=true

Authenticate with LDAP credentials:

curl -X POST http://localhost:8080/api/v1/auths/ldap \
  -H "Content-Type: application/json" \
  -d '{
    "user": "jdoe",
    "password": "ldap_password"
  }'

user

string

required

LDAP username (value of LDAP_ATTRIBUTE_FOR_USERNAME)

password

string

required

LDAP password

Response: Same format as JWT sign-in (token, user details, etc.)

LDAP Group Synchronization

Automatically sync LDAP groups to Open WebUI groups:

ENABLE_LDAP_GROUP_MANAGEMENT=true
ENABLE_LDAP_GROUP_CREATION=true
LDAP_ATTRIBUTE_FOR_GROUPS=memberOf

When enabled:

Groups from memberOf attribute are synced on each login
New groups are created if ENABLE_LDAP_GROUP_CREATION=true
User group memberships are updated to match LDAP

5. Trusted Header Authentication

Delegate authentication to a reverse proxy or SSO gateway.

Configuration

WEBUI_AUTH_TRUSTED_EMAIL_HEADER=X-Forwarded-Email
WEBUI_AUTH_TRUSTED_NAME_HEADER=X-Forwarded-User
WEBUI_AUTH_TRUSTED_GROUPS_HEADER=X-Forwarded-Groups

Only use trusted headers behind a properly configured reverse proxy. Never expose this to the public internet.

How It Works

Reverse proxy authenticates the user
Proxy forwards user identity in HTTP headers
Open WebUI trusts these headers and creates/authenticates the user
Groups are synced if WEBUI_AUTH_TRUSTED_GROUPS_HEADER is set

Example Configuration (Nginx)

location / {
  proxy_set_header X-Forwarded-Email $remote_user;
  proxy_set_header X-Forwarded-User $http_x_forwarded_user;
  proxy_pass http://open-webui:8080;
}

Authentication Error Codes

Status	Error	Description
`401`	`Invalid credentials`	Incorrect email/password
`401`	`Invalid token`	JWT token is malformed or expired
`401`	`Not authenticated`	No authentication provided
`403`	`API key not allowed`	API keys disabled or user lacks permission
`403`	`API key not allowed to access this endpoint`	Endpoint restriction enabled
`403`	`Access prohibited`	User role insufficient for operation
`429`	`Rate limit exceeded`	Too many sign-in attempts

Security Best Practices

Do:

Use HTTPS in production to encrypt tokens in transit
Store API keys securely (environment variables, secrets manager)
Rotate API keys periodically
Use short-lived JWT tokens for interactive sessions
Enable Redis for token revocation
Implement endpoint restrictions for API keys
Use OAuth for SSO and centralized user management

Don’t:

Commit API keys or secrets to version control
Share API keys between users or applications
Use trusted header authentication without a reverse proxy
Disable authentication in production (WEBUI_AUTH=false)
Expose API keys in client-side code or URLs

Code Examples

Python

import requests

# Sign in and get JWT token
response = requests.post(
    "http://localhost:8080/api/v1/auths/signin",
    json={
        "email": "[email protected]",
        "password": "password123"
    }
)
data = response.json()
token = data["token"]

# Use token for authenticated requests
headers = {"Authorization": f"Bearer {token}"}
chats = requests.get(
    "http://localhost:8080/api/v1/chats",
    headers=headers
).json()

print(f"Retrieved {len(chats)} chats")

JavaScript (Node.js)

const axios = require('axios');

const BASE_URL = 'http://localhost:8080/api/v1';

// Sign in
async function signIn(email, password) {
  const response = await axios.post(`${BASE_URL}/auths/signin`, {
    email,
    password
  });
  return response.data.token;
}

// Use API with token
async function getChats(token) {
  const response = await axios.get(`${BASE_URL}/chats`, {
    headers: {
      'Authorization': `Bearer ${token}`
    }
  });
  return response.data;
}

// Example usage
(async () => {
  const token = await signIn('[email protected]', 'password123');
  const chats = await getChats(token);
  console.log(`Retrieved ${chats.length} chats`);
})();

cURL

# Sign in and extract token
TOKEN=$(curl -s -X POST http://localhost:8080/api/v1/auths/signin \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"password123"}' \
  | jq -r '.token')

# Use token for requests
curl http://localhost:8080/api/v1/chats \
  -H "Authorization: Bearer $TOKEN"

Overview

Chat & Messages

Models

Users & Groups

Knowledge

Functions & Tools

Files & Media

Channels

Prompts

Notes & Folders

Evaluations

Configuration

​Authentication

​Authentication Methods

​1. JWT Token Authentication

​Obtaining a JWT Token

​Using JWT Tokens

​Token Expiration

​Token Revocation

​2. API Key Authentication

​Generating an API Key

​Using API Keys

​API Key Requirements

​Retrieving Your API Key

​Deleting an API Key

​API Key Endpoint Restrictions

​3. OAuth 2.0 / OpenID Connect

​Supported Providers

​OAuth Configuration

​OAuth Flow

​OAuth Claims Mapping

​Role-Based Access with OAuth

​Account Merging

​Token Exchange (Advanced)

​4. LDAP Authentication

​LDAP Configuration

​LDAP Sign-In

​LDAP Group Synchronization

​5. Trusted Header Authentication

​Configuration

​How It Works

​Example Configuration (Nginx)

​Authentication Error Codes

​Security Best Practices

​Code Examples

​Python

​JavaScript (Node.js)

​cURL

​Next Steps

API Endpoints

User Management

Build docs developers (and LLMs) love

Authentication

Authentication Methods

1. JWT Token Authentication

Obtaining a JWT Token

Using JWT Tokens

Token Expiration

Token Revocation

2. API Key Authentication

Generating an API Key

Using API Keys

API Key Requirements

Retrieving Your API Key

Deleting an API Key

API Key Endpoint Restrictions

3. OAuth 2.0 / OpenID Connect

Supported Providers

OAuth Configuration

OAuth Flow

OAuth Claims Mapping

Role-Based Access with OAuth

Account Merging

Token Exchange (Advanced)

4. LDAP Authentication

LDAP Configuration

LDAP Sign-In

LDAP Group Synchronization

5. Trusted Header Authentication

Configuration

How It Works

Example Configuration (Nginx)

Authentication Error Codes

Security Best Practices

Code Examples

Python

JavaScript (Node.js)

cURL

Next Steps