Authentication Mechanisms
Thepalyrad daemon exposes several HTTP route groups, each governed by different authentication and security requirements.
Admin API (Bearer Token)
The/admin/v1/ routes are used for low-level system management and CLI interactions.
- Mechanism: Static Bearer Token.
- Requirements: Requests must include an
Authorization: Bearer <token>header along with context headers:x-palyra-principal,x-palyra-device-id, andx-palyra-channelcrates/palyra-daemon/tests/admin_surface.rs#48-61. - Rate Limiting: Protected by
admin_rate_limit_middlewarewhich enforces per-IP buckets to prevent brute-force attempts crates/palyra-daemon/src/transport/http/middleware.rs#172-204.
Web Console (Session Cookie + CSRF)
The/console/v1/ routes serve the React-based operator dashboard.
- Session Management: Uses an encrypted,
HttpOnlysession cookie refreshed automatically byconsole_session_cookie_refresh_middlewarecrates/palyra-daemon/src/transport/http/middleware.rs#87-107. - CSRF Protection: Mutating requests (POST/PUT/DELETE) require a valid
x-palyra-csrf-tokenheader matching the session state apps/web/src/consoleApi.test.ts#44-90. - Security Headers: All responses include
no-storecache controls and strictContent-Security-Policyto prevent framing and sniffing crates/palyra-daemon/src/transport/http/middleware.rs#37-52.
Data Flow: Web Console Authentication
The following diagram illustrates the lifecycle of a web console session, from initial bootstrap to authenticated mutation. Web Console Auth Sequence Sources: apps/web/src/consoleApi.test.ts#44-64, crates/palyra-daemon/src/transport/http/middleware.rs#87-107, crates/palyra-daemon/src/transport/http/handlers/web_ui.rs#16-34OpenAI OAuth and Profile Registry
Thepalyra-auth crate manages model provider credentials via an AuthProfileRegistry crates/palyra-auth/src/lib.rs#21-21. It supports both static API keys and dynamic OAuth2 flows.
OAuth Bootstrap Flow
For OpenAI, Palyra implements a PKCE-based OAuth2 flow to obtain refresh tokens, ensuring the daemon can autonomously rotate access tokens.- Bootstrap: The operator initiates the flow via
start_openai_oauth_attempt_from_request, which generates a PKCE verifier and challenge crates/palyra-daemon/src/openai_surface.rs#68-112. - Redirection: The daemon constructs an authorization URL pointing to
auth.openai.comcrates/palyra-daemon/src/openai_auth.rs#109-130. - Callback: Upon return to
console/v1/auth/providers/openai/callback, the daemon exchanges the authorization code for anaccess_tokenandrefresh_tokencrates/palyra-daemon/src/openai_auth.rs#132-187. - Persistence: Credentials are encrypted and stored in the Vault as
AuthProfileRecordentries crates/palyra-daemon/src/openai_surface.rs#35-54.
Profile Registry Entities
| Entity | Role | Source |
|---|---|---|
AuthProfileRecord | Persisted record of a provider’s credential and scope. | crates/palyra-auth/src/lib.rs#13-13 |
AuthCredentialType | Enum: ApiKey, OAuth2, or None. | crates/palyra-auth/src/lib.rs#10-12 |
OAuthRefreshAdapter | Trait for handling background token rotation. | crates/palyra-auth/src/lib.rs#18-20 |
AuthProfileRegistry | Orchestrates storage and retrieval of auth profiles. | crates/palyra-auth/src/lib.rs#21-21 |
Browser Handoff Mechanism
To provide a seamless transition from the Desktop Application (Tauri) to the Web Dashboard, Palyra uses a “Browser Handoff” token.- Generation: The desktop app generates a short-lived
desktop_handoff_token. - Transfer: The desktop app opens the system browser to the dashboard URL with the token in the query string:
/?desktop_handoff_token=...apps/web/src/App.test.tsx#69-75. - Consumption: The web app’s
ConsoleAppdetects the token and callsPOST /console/v1/auth/browser-handoff/sessionapps/web/src/App.test.tsx#102-105. - Session Promotion: The daemon validates the handoff token and issues a full web session cookie, effectively logging the user in without requiring the manual admin token apps/web/src/App.test.tsx#109-147.
Configuration and Secrets
Auth profiles are often linked to the system configuration. When a profile is selected as default, the daemon updates themodel_provider.auth_profile_id in the local palyra.toml crates/palyra-daemon/tests/openai_auth_surface.rs#118-125. Raw secrets like API keys are never stored in plain text in the config; they are always abstracted behind a VaultRef crates/palyra-daemon/tests/openai_auth_surface.rs#92-104.
Sources: crates/palyra-daemon/src/openai_surface.rs#35-57, crates/palyra-daemon/tests/openai_auth_surface.rs#29-146