Security & compliance

Security and keys

Authentication

Runtime API: Bearer token with a project API key (sk_live_… / sk-test-…) or a Keycloak access JWT for a user with organisation membership. Each key has HRN-based scopes covering specific route patterns; the server checks that at least one scope on the key matches the route’s required HRN. Admin API: only a verified Keycloak access JWT in Authorization: Bearer (same contract as OIDC sign-in to the web console). Web console: Keycloak OIDC with JWT tokens. Session management via keycloak-js. Users must be members of the target organisation.

Encryption at rest

All sensitive data — secrets, LLM provider keys, session events, contextVars — is encrypted at rest using AES-256-GCM. PlanVault uses envelope encryption: each organisation has a DEK wrapped under deployment key hierarchy (**typical hosted SaaS:** Google Tink with an **AWS KMS**–backed key encryption key; **legacy orgs:** direct AWS KMS wrap of raw DEK bytes; **self-hosted:** operator-supplied KEK material per deployment guide). Plaintext DEK exists in memory only while unwrap succeeds.

DEK rotation can be triggered by an OWNER or ADMIN via the console or Admin API. A background worker re-encrypts all affected rows. During a healthy rotation (status IN_PROGRESS), new encrypted writes use the pending DEK version; if rotation metadata is inconsistent, those writes fail closed with HTTP 409 Conflict. CMK or IAM policy changes for KMS are operator/AWS procedures outside the PlanVault console.

Runtime API keys (project)

Calls to /api/v1/projects/{projectId}/… accept a Bearer token from any valid key for that project (primary or additional) whose scopes cover the route’s required HRN. Plaintext is shown only at issuance or right after rotation. The console stores the primary key in per-user server-side UI preferences; keep integration secrets in your own systems. Do not embed keys in public frontends or source repos.

Roles & access control

Four organisation membership roles exist (stored uppercase): **OWNER**, **ADMIN**, **DEVELOPER**, **MEMBER**. **OWNER** and **ADMIN** share the privileged Owner/Admin gate: organisation soft-delete, DEK rotation, invitations and role changes, audit log listing, minting and rotating Runtime API keys (including primary), org/project LLM budget caps, session and audit retention, and outbound HTTP policy overrides where the API requires Owner/Admin. **OWNER-only** API surfaces include toggling **Semantic Routing Cache** (auto-scenario embedding cache) and organisation-wide **debug content access**. **DEVELOPER** uses Admin APIs guarded by “Developer or higher”: tool catalog, OpenAPI/MCP, scenarios, many LLM/integration settings, org/project secrets, **creating projects**; **cannot** manage membership, read audit logs, rotate the org DEK, delete the organisation, mint or rotate Runtime keys, or change budget caps / retention / outbound HTTP overrides. **MEMBER** uses chats and projects; Admin API catalog/scenario management returns **HTTP 403**. For **Runtime JWT** calls, HRN scopes come from `RoleScopeResolver`: Members get a narrow session/chat/history grant set; Developers get broader session/tools coverage but are denied selected writes (project integrations, session secrets, scheduled/recurring schedule writes). **Project API keys** are authorised from the key’s scopes alone, independent of the user’s org role.

GDPR and data

Where to manage retention and how to download copies for portability and data-subject requests. Legal artefacts (DPA, ROPA, subprocessors) remain your organisation’s responsibility.

Organisation data and retention

On this page: session retention; JSON export for the whole organisation; external user field with per-user export and erasure of that user’s sessions within the org; DEK rotation. JSON exports include decrypted event history; secret names may appear, secret values are never included. A full organisation archive may include summarised membership information and transparency metadata for routing suggestions (without embedding vectors), when permitted by export policy.

Project data export (GDPR)

Download a JSON archive for a single project (sessions and events in that project; secret values are not exported).

Deletion and auto-pruning

Deleting an organisation in the UI removes its projects, sessions, and related rows in the PlanVault database. Copies at external LLM providers, infrastructure logs, or your own backups still need separate handling.

Session retention (days) controls when the background job may prune sessions for the organisation (0 means no automatic pruning by this setting).

Admin API and automation

The same and additional operations (org/project export, per–external-user erasure, DEK rotation, and more) are available via the Admin API with a verified Keycloak access JWT (typically after console sign-in, or from your IdP for approved automation). See API docs and Swagger for endpoint reference and embedded Swagger.