Auth Profile Registry and OAuth

The palyra-auth crate and the associated openai_surface.rs in the daemon provide a centralized system for managing credentials for model providers (OpenAI, Anthropic). This system handles secure storage of API keys and OAuth tokens, automated refresh flows, and health monitoring for authentication states.

Auth Profile Registry

The AuthProfileRegistry is the core entity responsible for managing the lifecycle of authentication profiles. Each profile associates a provider (e.g., OpenAI) with a specific credential and a scope (Global or Agent-specific) [crates/palyra-auth/src/lib.rs#10-21](http://crates/palyra-auth/src/lib.rs#10-21).

Implementation Details

Credential Storage: Raw secrets are never stored in the registry itself. Instead, the registry stores “vault references” (URIs) that point to encrypted blobs in the palyra-vault [crates/palyra-daemon/src/openai_surface.rs#42-48](http://crates/palyra-daemon/src/openai_surface.rs#42-48).
Scoping: Profiles can be scoped to Global (available to all runs) or Agent (restricted to a specific agent_id) [crates/palyra-auth/src/models.rs#10-16](http://crates/palyra-auth/src/models.rs#10-16).
Persistence: Profiles are typically persisted as part of the daemon’s configuration system, allowing for portability across environments while keeping secrets in the local vault [crates/palyra-daemon/src/openai_surface.rs#61-61](http://crates/palyra-daemon/src/openai_surface.rs#61-61).

Auth Profile Data Flow

This diagram illustrates how a request to connect an API key flows from the Web Console through the Daemon to the Vault. Title: API Key Connection Data Flow Sources: [apps/web/src/console/sections/AuthSection.tsx#130-166](http://apps/web/src/console/sections/AuthSection.tsx#130-166), [apps/web/src/console/hooks/useAuthDomain.ts#130-166](http://apps/web/src/console/hooks/useAuthDomain.ts#130-166), [crates/palyra-daemon/src/openai_surface.rs#18-78](http://crates/palyra-daemon/src/openai_surface.rs#18-78).

OAuth and PKCE Surface

Palyra implements a robust OAuth 2.0 flow with Proof Key for Code Exchange (PKCE) for OpenAI. This allows users to authorize Palyra without manually handling long-lived API keys.

PKCE Implementation

The system generates a cryptographically secure code_verifier and a corresponding code_challenge using SHA-256 [crates/palyra-daemon/src/openai_auth.rs#99-107](http://crates/palyra-daemon/src/openai_auth.rs#99-107).

Bootstrap: The operator initiates a flow which generates a state and code_challenge [crates/palyra-daemon/src/openai_auth.rs#109-130](http://crates/palyra-daemon/src/openai_auth.rs#109-130).
Callback: The daemon hosts a callback endpoint (/console/v1/auth/providers/openai/callback) that receives the authorization code [crates/palyra-daemon/src/openai_surface.rs#15-15](http://crates/palyra-daemon/src/openai_surface.rs#15-15).
Exchange: The daemon exchanges the code and the original code_verifier for an access_token and refresh_token [crates/palyra-daemon/src/openai_auth.rs#132-187](http://crates/palyra-daemon/src/openai_auth.rs#132-187).

Token Refresh Flow

The OAuthRefreshAdapter trait defines how tokens are renewed before expiry [crates/palyra-auth/src/refresh.rs#18-20](http://crates/palyra-auth/src/refresh.rs#18-20). The daemon runs background tasks to check for expiring tokens and uses the stored refresh_token_vault_ref to perform a silent exchange with the provider.

Provider Health and Validation

To ensure high availability, the palyra-auth system performs periodic health checks on all registered profiles.

Component	Functionality
Validation	Hits provider-specific endpoints (e.g., `/v1/models` for OpenAI) to verify token validity `[crates/palyra-daemon/src/openai_auth.rs#189-200](http://crates/palyra-daemon/src/openai_auth.rs#189-200)`.
Health Reporting	Aggregates profile states into `AuthHealthReport` (OK, Expiring, Expired, Missing) `[crates/palyra-auth/src/models.rs#10-16](http://crates/palyra-auth/src/models.rs#10-16)`.
Backoff	Implements `ProviderBackoffPolicy` to avoid spamming provider endpoints during outages `[crates/palyra-auth/src/refresh.rs#18-20](http://crates/palyra-auth/src/refresh.rs#18-20)`.

Title: Health Monitoring and Validation Loop Sources: [crates/palyra-daemon/src/openai_auth.rs#189-200](http://crates/palyra-daemon/src/openai_auth.rs#189-200), [crates/palyra-auth/src/lib.rs#10-16](http://crates/palyra-auth/src/lib.rs#10-16), [apps/web/src/console/hooks/useAuthDomain.ts#96-116](http://apps/web/src/console/hooks/useAuthDomain.ts#96-116).

CLI and Console Integration

CLI Commands

The palyra CLI provides comprehensive management for auth profiles via the auth command group [crates/palyra-cli/src/args/auth.rs#3-17](http://crates/palyra-cli/src/args/auth.rs#3-17):

palyra auth profiles list: Lists all registered profiles and their credential types [crates/palyra-cli/src/commands/auth.rs#42-96](http://crates/palyra-cli/src/commands/auth.rs#42-96).
palyra auth openai api-key: Interactively connects an OpenAI key, supporting stdin and environment variables [crates/palyra-cli/src/args/auth.rs#98-117](http://crates/palyra-cli/src/args/auth.rs#98-117).
palyra auth openai oauth-start: Initiates the PKCE flow and optionally opens the browser [crates/palyra-cli/src/args/auth.rs#118-143](http://crates/palyra-cli/src/args/auth.rs#118-143).

Web Console (AuthSection)

The Web Console provides a high-level UI for managing these profiles. It uses the useAuthDomain hook to synchronize state with the daemon [apps/web/src/console/hooks/useAuthDomain.ts#48-73](http://apps/web/src/console/hooks/useAuthDomain.ts#48-73).

Profile Inventory: Displays a sortable list of profiles with health status chips [apps/web/src/console/sections/AuthSection.tsx#62-111](http://apps/web/src/console/sections/AuthSection.tsx#62-111).
Connection Wizards: Step-by-step forms for both API Key and OAuth connection types [apps/web/src/console/sections/AuthSection.tsx#146-160](http://apps/web/src/console/sections/AuthSection.tsx#146-160).

Sources: [crates/palyra-cli/src/commands/auth.rs#4-25](http://crates/palyra-cli/src/commands/auth.rs#4-25), [apps/web/src/console/sections/AuthSection.tsx#83-144](http://apps/web/src/console/sections/AuthSection.tsx#83-144), [crates/palyra-daemon/src/openai_surface.rs#144-188](http://crates/palyra-daemon/src/openai_surface.rs#144-188).