Identity & The Principal Concept
The core unit of identity in Palyra is thePrincipal. Every request processed by the palyrad gateway or Admin API is associated with a principal string that identifies the actor.
- Console Admin: Typically represented as
admin:web-console. This principal is used for managing the daemon’s configuration, auth profiles, and vault secrets crates/palyra-daemon/tests/openai_auth_surface.rs#23-23. - API Tokens: Programmatic principals generated for external integrations.
- Channel Principals: Identities derived from external connectors (e.g., Discord user IDs).
access_control.rs module defines the WorkspaceRole enum, which maps principals to specific permission sets like Owner, Admin, and Operator crates/palyra-daemon/src/access_control.rs#76-80.
Permissions Mapping
| Role | Key Permissions |
|---|---|
| Owner | All permissions, including api_tokens.manage, trust.operate, and rollout.manage crates/palyra-daemon/src/access_control.rs#114-123. |
| Admin | Management of tokens, memberships, and sharing crates/palyra-daemon/src/access_control.rs#124-129. |
| Operator | Usage-focused: sessions.use, memory.use, and compat.chat.create crates/palyra-daemon/src/access_control.rs#104-112. |
Auth Profile Management (palyra-auth)
The palyra-auth crate manages credentials for external Model Providers (OpenAI, Anthropic). It abstracts the complexity of API keys and OAuth2 flows into a unified AuthProfileRecord crates/palyra-auth/src/lib.rs#10-16.
Credential Lifecycle
- Ingestion: Credentials enter the system via the Web Console or CLI.
- Validation: The daemon performs a “pre-flight” check against the provider (e.g., calling
/v1/models) to ensure the key is valid before saving crates/palyra-daemon/src/openai_surface.rs#32-38. - Vault Storage: Raw keys are never stored in the main configuration. They are persisted in the
palyra-vaultand referenced via avault_refcrates/palyra-daemon/src/openai_surface.rs#40-46. - Selection: A profile is marked as the “default” for a specific provider kind, which the orchestrator then uses for model calls crates/palyra-daemon/src/openai_surface.rs#60-68.
Code Entity Relationship: Auth Flow
The following diagram illustrates the flow from a Natural Language request in the UI to the underlying Rust entities. Title: Auth Profile Creation Flow Sources: apps/web/src/console/hooks/useAuthDomain.ts#130-166, crates/palyra-daemon/src/openai_surface.rs#16-76, crates/palyra-daemon/src/openai_auth.rs#189-195OpenAI-Compatible Auth Surface
Palyra provides a compatibility layer (compat.rs) that allows external tools to use Palyra as if it were the OpenAI API. This surface is protected by AuthenticatedApiToken crates/palyra-daemon/src/transport/http/handlers/compat.rs#78-88.
- Token Validation: The
authorize_compat_api_tokenfunction verifies theAuthorization: Bearer <token>header against theAccessRegistrycrates/palyra-daemon/src/transport/http/handlers/compat.rs#110-110. - Rate Limiting: Every compat token can have a
rate_limit_per_minute(defaulting to 120), enforced byenforce_compat_rate_limitcrates/palyra-daemon/src/transport/http/handlers/compat.rs#111-111. - Redaction: Sensitive headers and tokens are automatically redacted in logs using the
palyra-common::redactionutility to prevent credential leakage crates/palyra-common/src/redaction.rs#5-22.
Access Control Implementation
Access control logic is centralized inaccess_control.rs, which manages the access_registry.json file crates/palyra-daemon/src/access_control.rs#13-14.
Title: Access Control Architecture
Sources: crates/palyra-daemon/src/access_control.rs#137-183, crates/palyra-daemon/src/transport/http/handlers/compat.rs#1-10
CLI Authentication Commands
The CLI provides a comprehensive suite for managing identities and profiles without the Web Console.palyra auth profiles list: Calls the gRPCListProfilesmethod to show configured credentials crates/palyra-cli/src/commands/auth.rs#51-67.palyra auth profiles set: Configures a new profile, allowing manual specification ofapi-key-refor OAuth details crates/palyra-cli/src/commands/auth.rs#122-160.palyra auth access: Manages API tokens and permissions directly in theAccessRegistry.
Command Dispatch Example
When a user runspalyra auth profiles list, the CLI:
- Resolves a gRPC connection to the Admin endpoint crates/palyra-cli/src/commands/auth.rs#9-12.
- Constructs a
ListAuthProfilesRequestwith filters for provider kind or scope crates/palyra-cli/src/commands/auth.rs#51-63. - Injects necessary metadata (tokens/CSRF) into the request crates/palyra-cli/src/commands/auth.rs#64-64.
Security Middleware & CSRF
The Admin API (used by the Web Console) employs strict security measures:- CSRF Protection: Every state-changing request (POST/PUT/DELETE) requires a
x-palyra-csrf-tokenheader, which is validated against the session cookie crates/palyra-daemon/tests/openai_auth_surface.rs#43-57. - Secret Redaction: The
redact_tokenandredact_cookiefunctions ensure that even if logs are captured, sensitive values are replaced with<redacted>crates/palyra-common/src/redaction.rs#31-46. - Secure Storage: The
store_openai_secretfunction ensures that secrets are scoped to specific profiles and stored in the encrypted vault crates/palyra-daemon/src/openai_surface.rs#40-46.