Skip to main content
Palyra implements a multi-tiered security model that governs administrative access, user sessions, and model provider integrations. This system ensures that sensitive operations—such as modifying configuration or accessing API keys—are protected by robust authentication mechanisms while providing a seamless experience for the web console and CLI.

​
Admin Authentication & Principal Binding

The daemon enforces administrative security through a combination of static tokens and principal binding. This is the primary gate for all REST and gRPC operations that modify the system state.

​
Admin Token Auth

When administrative authentication is enabled via PALYRA_ADMIN_REQUIRE_AUTH, the daemon requires a Bearer token in the Authorization header crates/palyra-daemon/src/transport/http/handlers/console/auth.rs#41-45. This token is validated against the configured admin_token.

​
Principal Binding

The system uses “Principals” to identify the actor performing an operation. For the web console, the principal must follow the admin:* pattern (e.g., admin:web-console) crates/palyra-daemon/src/transport/http/handlers/console/auth.rs#31-35.

​
Authentication Data Flow

The following diagram illustrates the transition from a raw HTTP request to an authorized application context. Admin Auth Sequence Sources: crates/palyra-daemon/src/transport/http/handlers/console/auth.rs#19-111, crates/palyra-daemon/src/app/state.rs#1-50

​
Console Session & CSRF Model

The Web Console uses a stateful session model backed by secure cookies and CSRF (Cross-Site Request Forgery) protection.

​
Session Lifecycle

  1. Login: Upon successful admin token validation, the daemon calls issue_console_session crates/palyra-daemon/src/transport/http/handlers/console/auth.rs#101-101.
  2. Session Store: Sessions are stored in an in-memory map within AppState as ConsoleSession objects crates/palyra-daemon/src/app/runtime.rs#70-70.
  3. Token Issuance: A random session_token is minted and returned to the client via a Set-Cookie header crates/palyra-daemon/src/transport/http/handlers/console/auth.rs#104-106.

​
CSRF Protection

Every ConsoleSession includes a unique csrf_token crates/palyra-control-plane/src/models.rs#13-13.

​
Browser Handoff

To support transitions from the CLI to the Web Console (e.g., palyra console), the daemon implements a handoff mechanism. It generates a short-lived ConsoleBrowserHandoff token crates/palyra-daemon/src/transport/http/handlers/console/auth.rs#141-147 which is consumed by the browser to establish a session without re-entering the admin token. Sources: crates/palyra-daemon/src/transport/http/handlers/console/auth.rs#127-160, crates/palyra-control-plane/src/models.rs#8-16

​
OpenAI-Compatible Auth Surface

Palyra provides a specialized auth surface for model providers (OpenAI and Anthropic), allowing users to manage API keys and OAuth profiles through the web console or CLI.

​
Auth Profiles

The palyra-auth crate defines the core registry for these credentials.

​
Validation Flow

When a user adds a new API key (e.g., via connect_openai_api_key), the daemon performs real-time validation by calling the provider’s /v1/models endpoint crates/palyra-daemon/src/openai_auth.rs#189-195. This ensures the key is valid before persisting it crates/palyra-daemon/src/openai_surface.rs#32-38.

​
OAuth Bootstrap

For OpenAI, Palyra supports a PKCE-based OAuth flow:
  1. Bootstrap: start_openai_oauth_attempt generates a PKCE verifier and challenge crates/palyra-daemon/src/openai_auth.rs#99-107.
  2. Callback: The daemon hosts a callback handler at console/v1/auth/providers/openai/callback to capture the authorization code crates/palyra-daemon/src/openai_surface.rs#13-13.
  3. Exchange: The daemon exchanges the code for tokens using exchange_authorization_code crates/palyra-daemon/src/openai_auth.rs#132-140.
Sources: crates/palyra-daemon/src/openai_surface.rs#16-76, crates/palyra-daemon/src/openai_auth.rs#1-187

​
The palyra-auth Crate

The palyra-auth crate is the library responsible for managing the lifecycle of authentication profiles and handling OAuth token refreshes.
ComponentRoleFile Reference
AuthProfileRegistryManages the persistence and lookup of AuthProfileRecords.crates/palyra-auth/src/registry.rs#21-21
OAuthRefreshAdapterTrait for performing provider-specific token refreshes.crates/palyra-auth/src/refresh.rs#18-18
AuthHealthReportAggregates the status of all configured profiles (valid, expiring, or failed).crates/palyra-auth/src/models.rs#11-11
compute_backoff_msImplements exponential backoff for failed credential validations.crates/palyra-auth/src/refresh.rs#17-17

​
Profile Scoping

Profiles can be scoped to either Global (available to all agents) or Agent (restricted to a specific agent_id) crates/palyra-auth/src/models.rs#13-13. This is enforced during the model provider selection process. Sources: crates/palyra-auth/src/lib.rs#1-33

​
Access Control Layer

The Access Control layer manages the AccessRegistry, which tracks permissions and identity mappings within the daemon.

​
Implementation Mapping

The following diagram bridges the logical access control concepts to the specific code entities implementing them. Code Entity Mapping: Access Control Sources: crates/palyra-daemon/src/access_control.rs#1-20, crates/palyra-daemon/src/app/runtime.rs#11-16, palyra-identity: IdentityManager

​
Rate Limiting

The daemon implements tiered rate limiting to prevent abuse:

​
CLI Access Management

The CLI provides commands to manage these settings directly via palyra auth access crates/palyra-cli/src/commands/auth.rs#16-19, which communicates with the AuthService gRPC endpoint crates/palyra-cli/src/commands/auth.rs#31-33. Sources: crates/palyra-daemon/src/app/runtime.rs#27-83, crates/palyra-cli/src/commands/auth.rs#1-139