Bichon's RBAC has two layers: global roles decide what a user can do system-wide, and account-scoped roles decide which accounts they can read or manage. A user's effective access is the union of both, further restricted by the optional per-user access controls described below.

See Authentication & RBAC for the built-in roles and the full permission list.

Creating usersCopy Anchor Link

The WebUI page is Users (/users); the same operation is POST /api/v1/users. Required fields:

Optional: description, avatar_base64, theme, language, and acl (below). Updating a user is POST /api/v1/users/{id} with the same fields; omitted fields are left unchanged. Deleting a user is DELETE /api/v1/users/{id} and can be placed under dual control.

Custom rolesCopy Anchor Link

Built-in roles are immutable. Create a role with POST /api/v1/roles:

{
  "name": "audit-reader",
  "role_type": "Global",
  "description": "Read-only audit access",
  "permissions": ["system:access", "compliance:audit"]
}

role_type is Global or Account. Account roles can only carry account-scoped permissions (for example data:read, data:delete). Role names cannot be empty and cannot reuse reserved built-in names (admin, manager, viewer). Update with POST /api/v1/roles/{id}, delete with DELETE /api/v1/roles/{id}.

Scoping access to accountsCopy Anchor Link

Account-scoped assignment lives in a user's account_access_map. Two built-in account roles are the common choices:

• AccountManager (account_manager) — full control of the assigned account: configuration, sync, read/write/delete, import, SMTP ingest.
• AccountViewer (account_viewer) — read-only access to the assigned account's messages and metadata.

Assignments can also be made in bulk with POST /api/v1/accounts/access/assignments:

{ "user_ids": [3, 4], "account_ids": [12, 27], "role_id": 9 }

To create or edit a View account, the operator needs account:manage on every source account. Granting someone else the view is a separate step: assign them data:read on the view account itself. See Accounts → View.

Per-user access controlsCopy Anchor Link

Each user can carry an optional acl object, enforced on every authenticated request — including requests made with API tokens and including administrators:

{
  "acl": {
    "ip_whitelist": ["203.0.113.10", "2001:db8::10"],
    "rate_limit": { "interval": 60, "quota": 120 }
  }
}

The rate limit is per user, across all of that user's tokens and WebUI sessions.

API tokensCopy Anchor Link

API tokens are long-lived bearer credentials used by scripts, SMTP clients, and monitoring. Manage them under Settings → API Tokens or /users/api-tokens.

Create body:

{
  "name": "backup-script",
  "expire_in": 720,
  "metrics_only": false
}

• expire_in is optional and expressed in hours; omit it for a non-expiring token.
• metrics_only: true creates a token accepted only on GET /api/v1/metrics. The owner must hold system:metrics. See Monitoring & Metrics.
• The token is shown once at creation; store it immediately.

A token is sent as Authorization: Bearer <token>. The same token can be used as the SMTP password — see Embedded SMTP Receiver. Revoking a token invalidates both uses immediately, and token.revoke can be gated by dual control.

Tokens inherit the owning user's permissions and ACL: rotating a token does not widen access, and deleting the user invalidates their tokens.

Two-factor authenticationCopy Anchor Link

TOTP MFA is enabled per user under Settings → Two-factor Auth. Once enabled, login requires POST /api/auth/mfa/verify. Enabling and disabling MFA, and an administrator reset, are recorded as audit events on Pro/Enterprise. See Authentication & RBAC.