Domma CMS uses JWT-based authentication for all admin operations. The role-and-permission system allows granular access control across 11 resource types. Authentication is handled server-side by Fastify routes, with tokens stored in localStorage on the client.

The login sequence follows a standard JWT handshake with automatic silent refresh.

1. User visits /admin — redirected to login if not authenticated
2. Enter email and password — POST /api/auth/login
3. Server validates credentials (bcrypt compare) — returns { accessToken, refreshToken }
4. Access token stored in localStorage; refresh token stored in an httpOnly cookie
5. Subsequent requests include Authorization: Bearer {token} header
6. Access token expires in 15 minutes; auto-refreshed using refresh token (7 days)

Registration is intentionally restricted to prevent unauthorised account creation on production sites.

• Registration is disabled by default after initial setup
• First admin account created via npm run setup interactive wizard
• Additional users created by admins: Admin → Users → New User
• Optional: enable self-registration in config (auth.allowRegistration: true)
• When enabled, users self-register at /register with email verification (if SMTP is configured)
• New self-registered users are assigned the subscriber role by default

Password resets use a time-limited, single-use token delivered by email. SMTP must be configured in site settings for this flow to work.

1. User clicks "Forgot password" on the login page
2. Enter email address — POST /api/auth/forgot-password
3. If the email exists, the server sends a reset email with a time-limited token (1 hour)
4. User clicks the link — token is validated — user sets a new password
5. All existing sessions are invalidated immediately on password reset
6. Requires SMTP configured under Admin → Settings → Email

Domma CMS uses a two-token system to balance security (short-lived access) with usability (transparent refresh).

The JWT_SECRET is generated automatically during the npm run setup wizard and stored in your .env file. Rotate it by regenerating and restarting — all active sessions will be invalidated.

Token payload example: { "userId": "abc123", "email": "admin@example.com", "role": "admin", "iat": 1700000000, "exp": 1700000900 }

Built-in roles cover the most common team structures. Each role is cumulative — higher roles include all permissions of roles below them.

Custom roles let you define exactly the right access level for your team without over-provisioning permissions.

Every admin action is governed by a permission flag. The table below shows the default grants for each built-in role.

Pro resources (views, actions) are available on Pro and Enterprise plans. Custom roles can be configured with any combination of the above 44 flags.

Every authenticated user has an extended profile beyond their core auth fields. Profiles are stored as a preset collection linked to the auth user record by userId.

Use Domma CMS as a headless CMS by authenticating programmatically and including the access token with every request.

Login and obtain tokens

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

{
  "email": "admin@example.com",
  "password": "your-password"
}

// Response
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Use the access token in subsequent requests

GET /api/collections/posts/entries
Authorization: Bearer {accessToken}

Refresh the access token

POST /api/auth/refresh
Cookie: refreshToken={token}

// Response
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}