Sign-in methods
Users change their password from the user menu in the sidebar, which opens the change password dialog.
Frontend auth state
Auth state lives in:- Access token.
- Refresh token.
- Current user.
- Authentication status.
Authenticated requests
All authenticated frontend calls should use:- Adds
Authorization: Bearer <token>. - Refreshes tokens before requests when needed.
- Retries once after
401. - Logs out when refresh fails.
- Parses backend
detailerrors intoAuthError.
Route guards
Frontend guards live in:requireRoleLevel(level): Restricts navigation to users withrole_level <= level(or L99 auditor for admin views wherelevel <= 2).requireDocumentsAccess(): Legacy guard for shared document views (/share/d/$documentId). The/documentsmanagement route is now gated onrequireRoleLevel(2).requirePermission(permission): Checks capability permissions on the user’s authorization context.
Auditor Role (L99)
Users with role level 99 are read-only auditors:- Can view internal documents across applications and search the Knowledge Hub.
- Strictly forbidden from modifying documents, uploading new files, changing share policies, attaching documents to agents, or downloading raw document files. All mutation endpoints return
403 Forbidden.
Users who fail a guard are redirected to
/chat.
Role levels
Access grants
Grants control which users can use or edit a specific agent. A grant is created in one of three ways:
Grant endpoints:
Admins review and manage grants from the Users admin area at
/admin/users.
User directory & search authorization
The/api/identity/users/search endpoint implements role-aware authorization and field-level data minimization:
Protection mechanisms
- Data minimization: Low-privilege users never receive sensitive PII (
phone_number), administrative metadata (is_admin,role_assignments,role_level), or account security flags (use_sso,is_disabled,created_at). - Anti-enumeration: Calling without a search query or with fewer than 3 characters is rejected with
HTTP 400 Bad Requestfor non-admin callers. - Client debouncing: UI recipient pickers debounce queries with a 300ms delay to prevent request spamming during typing.