ConsoleApiClient is the primary TypeScript interface used by the Palyra Web Console to communicate with the palyrad daemon’s Admin and Console HTTP APIs. It encapsulates session management, security protocols (CSRF and Bound-Principals), and specialized data streaming for real-time chat and logs.
ConsoleApiClient Implementation
TheConsoleApiClient class is defined in apps/web/src/consoleApi.ts. It handles the lifecycle of HTTP requests, including the injection of security tokens and the parsing of NDJSON (Newline Delimited JSON) streams.
Key Functions and Methods
getSession(): Fetches the current session state from/console/v1/auth/sessionapps/web/src/consoleApi.test.ts#37-41.login(payload): Performs a login operation and initializes the internal CSRF token state apps/web/src/consoleApi.test.ts#67-72.fetch(path, init): A private wrapper around the globalfetchAPI that automatically attaches thex-palyra-csrf-tokenheader for mutating requests (POST, PUT, DELETE) apps/web/src/consoleApi.test.ts#82-90.- Streaming: Supports NDJSON streaming for chat runs and log tailing, allowing the UI to react to partial updates as they arrive from the daemon.
Data Flow: Request Lifecycle
The following diagram illustrates how a request from the React UI flows through theConsoleApiClient to the palyrad daemon.
Title: Web Console Request Pipeline
Sources: apps/web/src/consoleApi.ts#1-100, apps/web/src/consoleApi.test.ts#44-90
Authentication and Session Bootstrap
Palyra uses a multi-stage bootstrap process to establish a secure session between the browser and the daemon.Session Bootstrap Logic
The application attempts to recover a session in the following order:- Browser Handoff: If a
desktop_handoff_tokenis present in the URL (typically passed from the Desktop Companion), the client calls/console/v1/auth/browser-handoff/sessionapps/web/src/App.test.tsx#69-83. - Existing Session: If no handoff token exists, it attempts to refresh the current session via
/console/v1/auth/sessionapps/web/src/App.test.tsx#20-23. - Auth Screen: If both fail, the user is redirected to the
ConsoleAuthScreenapps/web/src/App.tsx#20-30.
CSRF Token Lifecycle
CSRF protection is enforced for all state-changing operations.- The token is issued during the initial session bootstrap or login apps/web/src/consoleApi.test.ts#46-53.
- The
ConsoleApiClientstores this token in memory and attaches it to thex-palyra-csrf-tokenheader apps/web/src/consoleApi.test.ts#86-89. - If a mutating request is attempted without a valid CSRF token, the client “fails closed” and throws an error apps/web/src/consoleApi.test.ts#92-106.
Security Constraints
Bound-Principal Security Lock
The daemon can be configured with a “Bound Principal” lock (viaPALYRA_ADMIN_BOUND_PRINCIPAL). This ensures that the Admin/Console API only accepts requests from a specific identity, such as admin:web-console crates/palyra-daemon/tests/admin_surface.rs#22-23.
Security Headers
The HTTP surface enforces strict security headers to prevent cross-site attacks:x-palyra-principal: Identifies the acting entity crates/palyra-daemon/tests/admin_surface.rs#49.x-palyra-device-id: Identifies the source hardware crates/palyra-daemon/tests/admin_surface.rs#50.Authorization: Bearer <token>: Standard bearer token for admin-level access crates/palyra-daemon/tests/admin_surface.rs#48.
Model Provider OAuth and API Key Flows
The Web Console facilitates the connection of Model Providers (OpenAI, Anthropic) through specialized flows that integrate with thepalyra-vault.
API Key Connection
Users can provide API keys directly through theAuthSection.
- The client calls
connectOpenAiApiKeyorconnectAnthropicApiKeyapps/web/src/console/hooks/useAuthDomain.ts#130-166. - The daemon validates the key against the provider’s
/v1/modelsendpoint crates/palyra-daemon/tests/openai_auth_surface.rs#138-143. - If valid, the key is stored in the Vault, and a
vault_refis returned to be stored in the configuration crates/palyra-daemon/tests/openai_auth_surface.rs#92-104.
OpenAI OAuth Flow
For OAuth-based authentication:- Bootstrap: Client calls
startOpenAiProviderBootstrapto get an authorization URL apps/web/src/console/hooks/useAuthDomain.ts#188-196. - Popup: A browser popup handles the external provider interaction apps/web/src/console/hooks/useAuthDomain.ts#71.
- Callback: The daemon receives the callback at
/console/v1/auth/providers/openai/callbackcrates/palyra-daemon/src/openai_surface.rs#13. - Polling: The Web Console polls
checkOpenAiCallbackStateuntil the exchange is complete apps/web/src/console/hooks/useAuthDomain.ts#86.
Error Handling
TheConsoleApiClient uses a structured error class, ControlPlaneApiError, to categorize failures:
- Validation Errors: 400 Bad Request, typically for invalid config or API keys apps/web/src/App.openai-auth.test.tsx#143-157.
- Authentication Errors: 401 Unauthorized or 403 Forbidden, triggering a redirect to the login screen apps/web/src/App.test.tsx#22.
- Rate Limiting: 429 Too Many Requests, which the
Appcomponent handles with an exponential backoff retry strategy during bootstrap apps/web/src/App.test.tsx#38-50.