Authentication

Authentication methods for the Open WebUI API

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

Sign in using the /api/v1/auths/signin endpoint:

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

Response:

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

email · 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

1. Redirect user to /oauth/{provider}/login
2. User authenticates with the provider
3. Provider redirects to callback URL with authorization code
4. Open WebUI exchanges code for tokens
5. 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

LDAP Sign-In

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

1. Reverse proxy authenticates the user
2. Proxy forwards user identity in HTTP headers
3. Open WebUI trusts these headers and creates/authenticates the user
4. 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": "[e-mail]",
        "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('[e-mail]', '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":"[e-mail]","password":"password123"}' \
  | jq -r '.token')

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

Next Steps

API Endpoints

Explore available API endpoints

User Management

Manage users and permissions