Skip to main content
The Palyra daemon (palyrad) exposes two primary HTTP API families via an Axum-based router: the Admin API (/admin/v1/*) and the Console API (/console/v1/*). These APIs provide the control plane for both the CLI and the React-based Web Dashboard.

​
Axum Router and Middleware Pipeline

The HTTP server is constructed using the axum framework crates/palyra-daemon/src/transport/http/router.rs#1-15. The router integrates multiple layers of middleware to ensure security, rate limiting, and diagnostic visibility.

​
Router Composition

The router is split into several sub-routers that are merged into the main application state crates/palyra-daemon/src/transport/http/router.rs#17-157:
  • Admin Routes: High-privilege endpoints for system-level management, such as journal inspection, policy explanation, and channel management.
  • Console Routes: Operator-facing endpoints used by the Web Dashboard for chat, session management, and configuration.
  • Health and Compatibility: Basic health checks (/healthz) and legacy compatibility layers.
  • Web UI: Static asset serving for the React dashboard crates/palyra-daemon/src/transport/http/handlers/web_ui.rs#16-34.

​
Security Middleware

Security is enforced through several layers:
  1. CSRF Protection: Console POST/PUT/DELETE requests require a x-palyra-csrf-token header that must match the token stored in the session crates/palyra-control-plane/src/client.rs#63-65.
  2. Security Headers: The admin_console_security_headers_middleware applies strict headers (HSTS, CSP, X-Frame-Options) to all admin and console responses crates/palyra-daemon/src/transport/http/router.rs#155-157.
  3. Rate Limiting: The admin_rate_limit_middleware prevents brute-force attempts against sensitive endpoints crates/palyra-daemon/src/transport/http/router.rs#151-154.

​
Dependency Injection: AppState

The entire router shares a global AppState crates/palyra-daemon/src/app/state.rs. This state is injected into every handler using Axum’s State extractor crates/palyra-daemon/src/transport/http/handlers/console/diagnostics.rs#6-7. Entity Mapping: HTTP Pipeline
System NameCode EntityRole
Main Routerbuild_routerEntry point for HTTP server definition crates/palyra-daemon/src/transport/http/router.rs#17
Shared StateAppStateContainer for JournalStore, Vault, and GatewayRuntime crates/palyra-daemon/src/app/state.rs
Admin Logicadmin::coreImplementation of /admin/v1 handlers crates/palyra-daemon/src/transport/http/router.rs#19
Console Logicconsole::*Implementation of /console/v1 handlers crates/palyra-daemon/src/transport/http/handlers/console/mod.rs
Sources: crates/palyra-daemon/src/transport/http/router.rs#1-175, crates/palyra-daemon/src/app/state.rs, crates/palyra-daemon/src/transport/http/handlers/web_ui.rs#11-125

​
Admin API (/admin/v1/*)

The Admin API is primarily consumed by the palyra CLI and internal automation. It requires a valid Authorization: Bearer <token> header and specific context headers like x-palyra-principal and x-palyra-device-id crates/palyra-daemon/tests/admin_surface.rs#56-62.

​
Key Admin Endpoints

Sources: crates/palyra-daemon/src/transport/http/router.rs#18-157, crates/palyra-daemon/tests/admin_surface.rs#31-150

​
Console API (/console/v1/*)

The Console API is the backend for the Web Dashboard. It uses session-based authentication via cookies and requires CSRF tokens for state-changing operations.

​
Session Management and Login

Authentication is initiated via console_login_handler crates/palyra-daemon/src/transport/http/handlers/console/auth.rs#19-23.
  1. The client sends a ConsoleLoginRequest containing the principal and device ID.
  2. The server validates the credentials against the GatewayAuthConfig crates/palyra-daemon/src/transport/http/handlers/console/auth.rs#88-89.
  3. If successful, the server issues a session token and sets a SET_COOKIE header crates/palyra-daemon/src/transport/http/handlers/console/auth.rs#101-106.
  4. The response includes a csrf_token which the client must include in subsequent non-GET requests crates/palyra-daemon/src/transport/http/handlers/console/auth.rs#109-110.

​
Diagnostics Pipeline

The /console/v1/diagnostics endpoint crates/palyra-daemon/src/transport/http/handlers/console/diagnostics.rs#6 provides a comprehensive snapshot of the system state for the “Operations” section of the dashboard. It aggregates data from:

​
Browser Handoff

To facilitate seamless transitions between the CLI and the Web UI, the console_browser_handoff_handler generates short-lived tokens that allow a browser to “bootstrap” into a session without re-authenticating crates/palyra-daemon/src/transport/http/handlers/console/auth.rs#127-160. Data Flow: Console Authentication & Diagnostics Sources: crates/palyra-daemon/src/transport/http/handlers/console/auth.rs#1-160, crates/palyra-daemon/src/transport/http/handlers/console/diagnostics.rs#1-130, crates/palyra-control-plane/src/client.rs#67-83

​
Web UI Serving

The daemon can serve the built React application directly. It resolves the apps/web/dist directory by checking the PALYRA_WEB_DIST_DIR environment variable or searching relative to the current executable crates/palyra-daemon/src/transport/http/handlers/web_ui.rs#125-148. The web_ui_entry_handler serves index.html for any path that doesn’t match a static file, allowing React Router to handle client-side navigation crates/palyra-daemon/src/transport/http/handlers/web_ui.rs#161-193. Entity Mapping: Console UI Structure
Dashboard SectionAPI EndpointUI Component
Chat/console/v1/chat/*ChatConsolePanel apps/web/src/console/ConsoleSectionContent.tsx#32
Usage/console/v1/diagnosticsUsageSection apps/web/src/console/ConsoleSectionContent.tsx#45
Approvals/console/v1/approvals/*ApprovalsSection apps/web/src/console/ConsoleSectionContent.tsx#79
Memory/console/v1/memory/*MemorySection apps/web/src/console/ConsoleSectionContent.tsx#89
Sources: crates/palyra-daemon/src/transport/http/handlers/web_ui.rs#1-160, apps/web/src/console/ConsoleSectionContent.tsx#1-108, apps/web/src/console/navigation.ts#54-74