Authentication

Overview

listmonk uses HTTP Basic Authentication for API requests. All API endpoints (except public endpoints) require authentication with a valid username and password.

Authentication Methods

Session-Based (Web UI)

The web dashboard uses session-based authentication with cookies. After logging in through the web interface, your session is maintained for subsequent requests.

HTTP Basic Auth (API)

For programmatic API access, use HTTP Basic Authentication with your listmonk username and password. Format: username:password encoded in Base64 in the Authorization header.

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Making Authenticated Requests

Using cURL

The simplest way to authenticate with cURL is using the -u flag:

curl -u 'username:password' http://localhost:9000/api/subscribers

Or with the Authorization header directly:

curl -H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
  http://localhost:9000/api/subscribers

Using Different Languages

Python
Node.js
Go
PHP

import requests
from requests.auth import HTTPBasicAuth

# Using requests library
response = requests.get(
    'http://localhost:9000/api/subscribers',
    auth=HTTPBasicAuth('username', 'password')
)

data = response.json()
print(data)

const axios = require('axios');

// Using axios
axios.get('http://localhost:9000/api/subscribers', {
  auth: {
    username: 'username',
    password: 'password'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error('Error:', error.response.data);
});

package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    client := &http.Client{}
    req, _ := http.NewRequest("GET", "http://localhost:9000/api/subscribers", nil)
    req.SetBasicAuth("username", "password")

    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

<?php
$ch = curl_init('http://localhost:9000/api/subscribers');
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$data = json_decode($response, true);

print_r($data);
curl_close($ch);
?>

User Types

listmonk supports two types of users, defined in the database schema:

Regular Users

Type: user
Purpose: Human users who log in to the web dashboard
Features: Can have 2FA enabled, full dashboard access
Status: Can be enabled or disabled

API Users

Type: api
Purpose: Programmatic API access without 2FA
Features: Designed for machine-to-machine communication
Status: Can be enabled or disabled

For automated integrations, create API users that bypass 2FA requirements while maintaining role-based permissions.

Creating Users

Initial Admin User

On first installation, you’ll create a super admin user through the setup wizard at http://localhost:9000/admin.

Adding Users via API

Create additional users with the users API:

curl -u 'admin:password' -X POST http://localhost:9000/api/users \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "[email protected]",
    "name": "API User",
    "password": "secure-password-here",
    "type": "api",
    "status": "enabled",
    "role_id": 1
  }'

Creating API Users

For programmatic access without 2FA:

curl -u 'admin:password' -X POST http://localhost:9000/api/users \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "[email protected]",
    "name": "Integration User",
    "password": "integration-api-key",
    "type": "api",
    "status": "enabled",
    "role_id": 2
  }'

Role-Based Access Control

listmonk implements fine-grained permissions through roles. Each user is assigned a role that defines which API endpoints and features they can access.

Permission Format

Permissions follow the pattern: resource:action Examples:

subscribers:get - View subscribers
subscribers:manage - Create, update, delete subscribers
campaigns:get - View campaigns
campaigns:manage - Create, update campaigns
settings:manage - Modify system settings

Checking User Permissions

Get the current user’s profile and permissions:

curl -u 'username:password' http://localhost:9000/api/profile

Response includes:

{
  "data": {
    "id": 1,
    "email": "[email protected]",
    "name": "User Name",
    "type": "user",
    "status": "enabled",
    "role": {
      "id": 1,
      "name": "Admin",
      "permissions": ["*"]
    }
  }
}

A role with ["*"] in permissions has full access to all resources.

OIDC Authentication

listmonk supports OpenID Connect (OIDC) for single sign-on with providers like Google, Azure AD, Okta, and Keycloak.

Configuration

Configure OIDC in your config.toml:

[app.security.oidc]
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 = 2

User clicks “Login with OIDC” on the login page
Redirected to OIDC provider for authentication
After successful authentication, redirected back to listmonk
If auto_create_users is enabled, a new user account is created automatically
User is logged in with assigned default role

Provider Setup Examples

Google OIDC

Go to Google Cloud Console
Create OAuth 2.0 credentials
Set authorized redirect URI: http://your-listmonk/api/auth/oidc/callback

Use these settings:

provider_url = "https://accounts.google.com"
client_id = "your-app-id.apps.googleusercontent.com"
client_secret = "your-secret"

Azure AD OIDC

Register an application in Azure AD
Set redirect URI: http://your-listmonk/api/auth/oidc/callback

Use these settings:

provider_url = "https://login.microsoftonline.com/{tenant-id}/v2.0"
client_id = "your-application-id"
client_secret = "your-secret"

Two-Factor Authentication (2FA)

Regular users can enable TOTP-based 2FA for enhanced security.

Enabling 2FA

Log in to the dashboard
Navigate to Settings → Profile
Click Enable Two-Factor Authentication
Scan the QR code with an authenticator app (Google Authenticator, Authy, etc.)
Enter the verification code to confirm

When 2FA is enabled:

Enter username and password
Enter the 6-digit TOTP code from your authenticator app
Successfully logged in

API users (type: api) cannot enable 2FA and are intended for machine-to-machine communication only.

Security Best Practices

Use Strong Passwords

Generate long, random passwords for API users. Consider using a password manager or secrets vault.

Rotate Credentials

Regularly rotate passwords, especially for API users and after team member departures.

Limit Permissions

Assign roles with minimum required permissions. Avoid giving all users admin access.

Use HTTPS

Always use HTTPS in production to encrypt credentials in transit. Never send credentials over plain HTTP.

Separate API Users

Create dedicated API users for each integration rather than sharing credentials.

Enable 2FA

Require 2FA for all regular users with administrative access.

Troubleshooting

401 Unauthorized

Problem: API returns 401 Unauthorized Solutions:

Verify username and password are correct
Check that the user account is enabled (status: enabled)
Ensure credentials are properly encoded in Base64
For API users, ensure type is set to api if 2FA is required for regular users

403 Forbidden

Problem: API returns 403 Forbidden Solutions:

User authenticated but lacks permission for the requested resource
Check the user’s role and permissions
Verify the role has the required permission (e.g., subscribers:manage)
Super admin role with ["*"] permission has access to all resources

Problem: OIDC authentication redirects fail Solutions:

Verify provider_url is correct and accessible
Check that redirect URI is registered with the OIDC provider
Ensure client_id and client_secret are correct
Check listmonk logs for detailed error messages

Next Steps

API Overview

Learn about response formats and pagination

Manage Subscribers

Start using the Subscribers API

API Overview

Endpoints

Overview

Authentication Methods

Session-Based (Web UI)

HTTP Basic Auth (API)

Making Authenticated Requests

Using cURL

Using Different Languages

User Types

Regular Users

API Users

Creating Users

Initial Admin User

Adding Users via API

Creating API Users

Role-Based Access Control

Permission Format

Checking User Permissions

OIDC Authentication

Configuration

Provider Setup Examples

Two-Factor Authentication (2FA)

Enabling 2FA

Security Best Practices

Use Strong Passwords

Rotate Credentials

Limit Permissions

Use HTTPS

Separate API Users

Enable 2FA

Troubleshooting

401 Unauthorized

403 Forbidden

Next Steps

API Overview

Manage Subscribers

Build docs developers (and LLMs) love

API Overview

Endpoints

​Overview

​Authentication Methods

​Session-Based (Web UI)

​HTTP Basic Auth (API)

​Making Authenticated Requests

​Using cURL

​Using Different Languages

​User Types

​Regular Users

​API Users

​Creating Users

​Initial Admin User

​Adding Users via API

​Creating API Users

​Role-Based Access Control

​Permission Format

​Checking User Permissions

​OIDC Authentication

​Configuration

​OIDC Login Flow

​Provider Setup Examples

​Two-Factor Authentication (2FA)

​Enabling 2FA

​2FA Login Flow

​Security Best Practices

Use Strong Passwords

Rotate Credentials

Limit Permissions

Use HTTPS

Separate API Users

Enable 2FA

​Troubleshooting

​401 Unauthorized

​403 Forbidden

​OIDC Login Fails

​Next Steps

API Overview

Manage Subscribers

Build docs developers (and LLMs) love

Overview

Authentication Methods

Session-Based (Web UI)

HTTP Basic Auth (API)

Making Authenticated Requests

Using cURL

Using Different Languages

User Types

Regular Users

API Users

Creating Users

Initial Admin User

Adding Users via API

Creating API Users

Role-Based Access Control

Permission Format

Checking User Permissions

OIDC Authentication

Configuration

OIDC Login Flow

Provider Setup Examples

Two-Factor Authentication (2FA)

Enabling 2FA

2FA Login Flow

Security Best Practices

Troubleshooting

401 Unauthorized

403 Forbidden

OIDC Login Fails

Next Steps