Authentication

User Management

listmonk supports multiple authentication methods and user management features. Users are managed through the Settings → Users dashboard in the admin interface.

Starting from recent versions, listmonk has moved away from config file-based credentials to database-managed users with role-based access control.

Initial Setup

On first launch, listmonk will prompt you to create a Super Admin user:

Access Setup Page

Navigate to http://localhost:9000/admin and you’ll see the first-time setup page.

Create Super Admin

Enter:

Email address
Username
Password (minimum 8 characters)
Confirm password

After creation, you’ll be automatically logged in and redirected to the dashboard.

Environment Variables for Setup

You can pre-configure the Super Admin credentials using environment variables:

LISTMONK_ADMIN_USER=myadmin LISTMONK_ADMIN_PASSWORD=mypassword ./listmonk --install

User Types

listmonk supports two types of users:

User

Regular users who log in through the web interface. Support password and OIDC authentication.

API

API-only users for programmatic access. Use username/password for HTTP Basic Authentication.

Role-Based Access Control

Users are assigned roles that define their permissions:

User Role

object

Defines what a user can do in the admin interface (view, create, edit campaigns, manage subscribers, etc.).

List Role

object

Defines which mailing lists a user can access. Can be restricted to specific lists.

The default Super Admin role (ID: 1) has all permissions and cannot be deleted.

Password Authentication

Standard username/password authentication for web interface users.

Password Requirements

Minimum length: 8 characters
No maximum length limit
No special character requirements (but recommended)

Password Reset

Users can reset their password through the login page:

Click Forgot Password

On the login page, click the “Forgot Password” link.

Enter Email

Enter the email address associated with your account.

Check Email

You’ll receive a password reset link (valid for 30 minutes).

Set New Password

Click the link and enter your new password.

Password reset emails are sent using the configured SMTP settings.

OIDC Authentication

listmonk supports OpenID Connect (OIDC) for single sign-on with external identity providers.

security.oidc.enabled

boolean

default:"false"

Enable OIDC authentication.

security.oidc.provider_url

string

required

OIDC provider’s discovery URL.Examples:

Google: https://accounts.google.com
Azure AD: https://login.microsoftonline.com/{tenant-id}/v2.0
Keycloak: https://keycloak.example.com/realms/{realm}

security.oidc.provider_name

string

default:""

Optional display name for the OIDC provider shown on the login page.If empty, listmonk will attempt to derive it from the provider URL.

security.oidc.client_id

string

required

OAuth 2.0 client ID from your OIDC provider.

security.oidc.client_secret

string

required

OAuth 2.0 client secret from your OIDC provider.

security.oidc.auto_create_users

boolean

default:"false"

Automatically create users on first OIDC login.

When enabled, any user who can authenticate with your OIDC provider will get access to listmonk.

security.oidc.default_user_role_id

integer

default:"null"

Default user role ID assigned to auto-created users.Required if auto_create_users is enabled.

security.oidc.default_list_role_id

integer

default:"null"

Default list role ID assigned to auto-created users.Optional. If not set, users get access to all lists.

OIDC Configuration Example

{
  "enabled": true,
  "provider_url": "https://accounts.google.com",
  "provider_name": "Google",
  "client_id": "your-client-id.apps.googleusercontent.com",
  "client_secret": "your-client-secret",
  "auto_create_users": true,
  "default_user_role_id": 2,
  "default_list_role_id": null
}

Supported OIDC Providers

listmonk has been tested with:

Google
Microsoft Azure AD / Entra ID
Keycloak
Auth0
Authentik
GitHub (via OIDC)

Any standard OIDC-compliant provider should work.

OIDC Setup Guide

Google OIDC Setup

Create OAuth 2.0 Client

Go to Google Cloud Console
Navigate to APIs & Services → Credentials
Create OAuth 2.0 Client ID (Web application)

Configure Redirect URI

Add: https://your-listmonk-domain.com/auth/oidc/callback

Get Credentials

Note the Client ID and Client Secret

Configure listmonk

In Settings → Security → OIDC:

Provider URL: https://accounts.google.com
Client ID and Secret from step 3

Azure AD OIDC Setup

Go to Azure Portal
Navigate to Azure Active Directory → App registrations
New registration

Configure Redirect URI

Add: https://your-listmonk-domain.com/auth/oidc/callback

Create Client Secret

Under Certificates & secrets, create a new client secret

Configure listmonk

Provider URL: https://login.microsoftonline.com/{tenant-id}/v2.0
Client ID: Application (client) ID
Client Secret: Value from step 3

Two-Factor Authentication (TOTP)

listmonk supports TOTP (Time-based One-Time Password) for additional security.

2FA is configured per user and is optional. Each user can enable it for their own account.

Enabling 2FA

Access Profile Settings

Click your username in the admin interface → Profile

Generate TOTP Secret

Click “Enable Two-Factor Authentication”

Scan QR Code

Use an authenticator app (Google Authenticator, Authy, 1Password, etc.) to scan the QR code

Verify Code

Enter the 6-digit code from your authenticator app to confirm

Enter username and password on the login page
If 2FA is enabled, you’ll be redirected to the 2FA verification page
Enter the current 6-digit code from your authenticator app
Upon successful verification, you’ll be logged in

If you lose access to your authenticator app, you’ll need a database administrator to disable 2FA for your account.

API Authentication

API users authenticate using HTTP Basic Authentication.

Creating an API User

Navigate to Users

Go to Settings → Users in the admin interface

Create New User

Click “New User” and select Type: “API”

Set Credentials

Username: API identifier
Password: API secret (minimum 8 characters)
Role: Assign appropriate permissions

Save

The username and password will be used for API authentication

Using API Credentials

curl -u username:password \
  https://listmonk.example.com/api/lists

Session Management

listmonk uses secure session cookies for web authentication.

Session Behavior

Sessions are stored in the PostgreSQL database
Session cookies are HTTP-only and use SameSite=Lax
Sessions persist across browser restarts
Logout clears the session from both browser and database

Session Security

All session cookies are marked as secure when accessed over HTTPS
CSRF protection using nonce tokens for OIDC flows
Session timeout is managed by the underlying session library

Legacy Credentials

If you have admin_username and admin_password in your config.toml file, remove them immediately and create users through the UI.

Legacy config-based credentials:

Are deprecated and show a warning banner
Should be migrated to database users
Will be removed in future versions

To migrate:

Create a new user through Settings → Users
Assign the Super Admin role
Test the new credentials
Remove admin_username and admin_password from config.toml
Restart listmonk

Security Best Practices

Use Strong Passwords

Require passwords of at least 12 characters with mixed case, numbers, and symbols.

Enable 2FA

Require all admin users to enable two-factor authentication.

Use OIDC

Centralize authentication with your organization’s identity provider.

Limit Permissions

Create custom roles with minimal required permissions for each user.

Separate API Users

Use dedicated API users for programmatic access, not personal accounts.

Regular Audits

Periodically review active users and remove unused accounts.

Get Started

Core Features

Configuration

Advanced

Development

User Management

Initial Setup

Environment Variables for Setup

User Types

User

API

Role-Based Access Control

Password Authentication

Password Requirements

Password Reset

OIDC Authentication

OIDC Configuration Example

Supported OIDC Providers

OIDC Setup Guide

Two-Factor Authentication (TOTP)

Enabling 2FA

API Authentication

Creating an API User

Using API Credentials

Session Management

Session Behavior

Session Security

Legacy Credentials

Security Best Practices

Use Strong Passwords

Enable 2FA

Use OIDC

Limit Permissions

Separate API Users

Regular Audits

Build docs developers (and LLMs) love

Get Started

Core Features

Configuration

Advanced

Development

​User Management

​Initial Setup

​Environment Variables for Setup

​User Types

User

API

​Role-Based Access Control

​Password Authentication

​Password Requirements

​Password Reset

​OIDC Authentication

​OIDC Configuration Example

​Supported OIDC Providers

​OIDC Setup Guide

​Two-Factor Authentication (TOTP)

​Enabling 2FA

​2FA Login Flow

​API Authentication

​Creating an API User

​Using API Credentials

​Session Management

​Session Behavior

​Session Security

​Legacy Credentials

​Security Best Practices

Use Strong Passwords

Enable 2FA

Use OIDC

Limit Permissions

Separate API Users

Regular Audits

Build docs developers (and LLMs) love

User Management

Initial Setup

Environment Variables for Setup

User Types

Role-Based Access Control

Password Authentication

Password Requirements

Password Reset

OIDC Authentication

OIDC Configuration Example

Supported OIDC Providers

OIDC Setup Guide

Two-Factor Authentication (TOTP)

Enabling 2FA

2FA Login Flow

API Authentication

Creating an API User

Using API Credentials

Session Management

Session Behavior

Session Security

Legacy Credentials

Security Best Practices