Authentication
POST /api/loginwith username + password returns a JWT access token- All
/api/v1/*endpoints requireAuthorization: Bearer <token> - Tokens expire after the configured duration (
BICHON_WEBUI_TOKEN_EXPIRATION_HOURS, default 7 days) - Long-lived API tokens can be created via WebUI or API for programmatic access
MFA / Two-Factor Authentication
TOTP-based two-factor authentication is built into the login flow (all editions, including Community). After enabling MFA on your profile, login requires a time-based one-time code verified via POST /api/auth/mfa/verify. Enable and disable events are recorded in the audit log on Pro/Enterprise.
Single Sign-On
- OIDC SSO (Keycloak, Okta, Microsoft Entra ID, Google Workspace, Auth0) — Pro edition. See Single Sign-On.
- LDAP / Active Directory bind-based sign-in — Enterprise edition. See Single Sign-On.
Default Admin Account
On first start, Bichon creates a built-in admin user:
- Username:
admin - Password:
admin@bichon
Important: Change the password immediately via WebUI: Settings → Profile. If locked out, use the
bichon-adminCLI tool to reset it.
Built-in Roles
| Role | Type | Scope | Description |
|---|---|---|---|
| Admin | Global | Unrestricted | Full system access — users, roles, tokens, all accounts, all data operations |
| Manager | Global | ACL-scoped | Create accounts, view users, manage authorized accounts and their data |
| Member | Global | Minimal | Basic login access; data access granted through account-level role assignments |
| AccountManager | Account | Per-account | Full control over an assigned account — config, sync, data read/write/delete, import, SMTP ingest |
| AccountViewer | Account | Per-account | Read-only access to an assigned account's messages and metadata |
Permission Reference
Global Permissions
| Permission | Description |
|---|---|
system:access | Login and access the dashboard |
system:root | Full system access and configuration; bypasses account ACLs |
system:metrics | Read the Prometheus metrics endpoint (GET /api/v1/metrics) |
user:manage | Create, update, and delete users |
user:view | View user list and basic profiles |
token:manage | View and revoke all API tokens |
account:create | Connect new email accounts to the system |
account:manage:all | Manage configurations for all email accounts |
data:read:all | Search and read messages across all accounts |
data:manage:all | Manage tags and metadata for all accounts |
data:raw:download:all | Download raw EML files from any account |
data:delete:all | Permanently delete messages from any account |
data:export:batch:all | Export messages in bulk from all accounts |
backup:manage | Trigger and manage backups, and browse backup data (restore points, manifests) |
legal:hold | Place or release legal holds on accounts (Enterprise) |
timestamp:manage | Manage RFC 3161 timestamp anchoring and verify per-email proofs (Enterprise) |
compliance:audit | Read-only compliance views: audit log, integrity reports, legal-hold status, anchors (Enterprise) |
approval:decide | Approve or reject dual-control requests for high-risk operations (Enterprise) |
Account-scoped Permissions (require ACL assignment)
| Permission | Description |
|---|---|
account:manage | Modify configuration and sync settings for authorized accounts |
account:read_details | View status and details of authorized accounts |
data:read | Read messages from authorized accounts |
data:manage | Manage tags and metadata for authorized accounts |
data:raw:download | Download raw EML files from authorized accounts |
data:delete | Delete messages from authorized accounts |
data:export:batch | Export messages from authorized accounts |
data:import:batch | Import EML/PST data into authorized accounts |
data:smtp:ingest | Receive and archive emails via SMTP for authorized accounts |
Tip: Built-in role permissions are immutable. Create custom roles via WebUI (
/users/roles) or API for any combination of the permissions above. For creating users, assigning account roles, IP/rate limits and API tokens, see Users & Access Control.