Pinter uses token-based authentication with refresh support. The frontend stores auth state in Zustand and sends bearer tokens through the shared authenticated request module.

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:
Stored fields include:
  • Access token.
  • Refresh token.
  • Current user.
  • Authentication status.
On rehydration, the store checks token expiry. Expired sessions are cleared unless the refresh token can still be used.

Authenticated requests

All authenticated frontend calls should use:
This module:
  • Adds Authorization: Bearer <token>.
  • Refreshes tokens before requests when needed.
  • Retries once after 401.
  • Logs out when refresh fails.
  • Parses backend detail errors into AuthError.

Route guards

Frontend guards live in:
Common guards include:
  • requireRoleLevel(level): Restricts navigation to users with role_level <= level (or L99 auditor for admin views where level <= 2).
  • requireDocumentsAccess(): Legacy guard for shared document views (/share/d/$documentId). The /documents management route is now gated on requireRoleLevel(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 Request for non-admin callers.
  • Client debouncing: UI recipient pickers debounce queries with a 300ms delay to prevent request spamming during typing.

Backend route groups

Backend routes use FastAPI dependencies such as active user and admin user checks. Common protected route groups:
Do not treat frontend guards as security controls. Backend dependencies and database authorization checks must enforce access.