Skip to main content
This page documents the security mechanisms governing access to the Palyra daemon, including the AccessRegistry for token-based authorization, the OpenAI-compatible API surface, and the management of provider credentials via the openai_auth surface.

​
AccessRegistry and Token Authorization

The AccessRegistry is the central authority for managing feature flags, API tokens, and workspace-level permissions within the daemon. It persists state to a JSON file and enforces Role-Based Access Control (RBAC) through predefined permissions associated with WorkspaceRole levels.

​
Workspace Roles and Permissions

Permissions are granular strings used to gate specific API handlers. The system defines three primary roles:
RoleDescriptionKey Permissions
OwnerFull control over the daemon and workspaces.api_tokens.manage, workspace.manage, trust.operate
AdminManagement of memberships and tokens.api_tokens.manage, workspace.memberships.manage
OperatorStandard usage of agent features.compat.chat.create, sessions.use, memory.use
Sources: [crates/palyra-daemon/src/access_control.rs#74-135](http://crates/palyra-daemon/src/access_control.rs#74-135), [crates/palyra-daemon/src/access_control.rs#24-36](http://crates/palyra-daemon/src/access_control.rs#24-36)

​
Token Implementation

API tokens are represented by ApiTokenRecord objects. Authentication involves verifying a token prefix and a SHA-256 hash of the full secret.

​
Access Control Data Flow

The following diagram illustrates how a request is authorized using the AccessRegistry. Figure 1: Access Control Authorization Flow Sources: [crates/palyra-daemon/src/transport/http/handlers/compat.rs#105-121](http://crates/palyra-daemon/src/transport/http/handlers/compat.rs#105-121), [crates/palyra-daemon/src/access_control.rs#151-173](http://crates/palyra-daemon/src/access_control.rs#151-173)

​
OpenAI Compatibility Surface

Palyra provides an OpenAI-compatible HTTP surface located at /v1/*. This allows existing tools and SDKs designed for OpenAI to interact with Palyra agents as if they were standard models.

​
Key Endpoints

​
Implementation Detail: prepare_compat_run

When a request hits the compatibility surface, the daemon converts the OpenAI-formatted payload into a Palyra Run. This involves:
  1. Authorization: Calling authorize_compat_api_token crates/palyra-daemon/src/transport/http/handlers/compat.rs#110-110.
  2. Prompt Rendering: Converting the messages array into a single prompt string via render_compat_messages_prompt crates/palyra-daemon/src/transport/http/handlers/compat.rs#133-133.
  3. Run Creation: Initializing a TonicRequest to the internal gRPC RunStream crates/palyra-daemon/src/transport/http/handlers/compat.rs#78-88.
Sources: [crates/palyra-daemon/src/transport/http/handlers/compat.rs#1-100](http://crates/palyra-daemon/src/transport/http/handlers/compat.rs#1-100)

​
OpenAI Auth and API Key Management

The openai_auth surface handles the secure acquisition and storage of API keys for providers like OpenAI and Anthropic. It ensures that raw keys are never stored in plain text in the main configuration.

​
Credential Storage via Vault

When a user connects an API key (e.g., via the Web Console), the following occurs:
  1. Validation: The daemon performs a pre-flight check against the provider’s /v1/models endpoint to ensure the key is valid crates/palyra-daemon/src/openai_surface.rs#34-40.
  2. Vaulting: The key is stored in the palyra-vault. Only a VaultRef (a secure reference) is stored in the AuthProfileView crates/palyra-daemon/src/openai_surface.rs#42-57.
  3. Profile Creation: An AuthProfileView is persisted, associating the VaultRef with a profile_id and a scope (Global or Agent-specific) crates/palyra-daemon/src/openai_surface.rs#61-61.

​
Code Entity Mapping: Auth Flow

The following diagram maps the UI actions in the React Console to the backend Rust functions. Figure 2: API Key Connection Flow Sources: [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), [crates/palyra-cli/src/commands/auth.rs#20-23](http://crates/palyra-cli/src/commands/auth.rs#20-23)

​
Dangerous Remote Bind Guards

For security, Palyra implements “dangerous remote bind” guards. If the daemon is configured to bind to a non-loopback interface (making it accessible over the network), it requires explicit acknowledgement. Sources: [crates/palyra-cli/src/commands/security.rs#152-190](http://crates/palyra-cli/src/commands/security.rs#152-190)