Security Model
Identity, tokens, API keys, the permission system, plugin sandboxing, and multi-tenant isolation.
Overview
Pomavo's security model rests on a few clear ideas: a dedicated identity service issues verifiable tokens, every request carries a tenant and a subject, a fine-grained permission system governs what that subject may do, and untrusted code runs in a sandbox. This page explains how those pieces fit together.
Identity and Tokens
Authentication is handled by a dedicated Auth service, separate from the application API. It manages sessions, supports OAuth sign-in, and issues signed tokens that the rest of the system verifies. Keeping identity in its own service means the application API never stores passwords or owns the login flow, it only verifies tokens it is handed.
Tokens are signed and verified using published signing keys, so any service can independently validate a token without calling back to the issuer on every request.
Treat signing keys and service credentials as deployment secrets. They belong in your environment's secret manager, not in source control or shared configuration. Rotate them on a schedule and on any suspected exposure.
API Keys
For non-interactive access, such as the MCP server, scripts, and integrations, Pomavo uses API keys bound to an organization. A key authenticates the caller and pins it to a single tenant, so an automated client can only ever operate within the organization it was issued for. Keys should be scoped narrowly, stored securely, and revoked when no longer needed.
The Permission System
Authentication answers who you are; permissions answer what you may do. Pomavo's permission system is fine-grained: capabilities are grouped into roles, roles are assigned to members, and every sensitive operation in the API is gated on a specific permission. The same checks apply whether an action comes from the UI, the API, a query mutation, or an AI agent, there is no privileged back door that skips them.
This uniformity is important: because query mutations and automations run through the same domain services as manual edits, they are subject to the same permission checks and produce the same audited events.
Multi-Tenant Isolation
Every record in Pomavo is scoped to an organization. Tenant context is established at the edge of every request and threaded through every layer - the API, the search index, the job pipeline, and the automation engine - so data from one organization is never visible to another.
Background work preserves this just as strictly: when the Worker processes a job or an automation runs, it carries the originating organization's context, and data-access gateways enforce that scope on every lookup. A job cannot read or write across tenant boundaries.
Plugin Sandboxing
Third-party plugins are untrusted by default. They run in a sandboxed iframe with a minimal capability grant and can communicate with Pomavo only through a structured, origin-validated message channel. A plugin receives a token scoped to the current user and a context limited to what it needs to do its job, never blanket access to the host application, its storage, or its credentials.
Defense in Depth
Separate identity service
Login and token issuance are isolated from the application API.
Verifiable tokens
Signed tokens are validated independently using published keys.
Permission-gated operations
Every sensitive action is checked against a specific permission, uniformly across all entry points.
Tenant scoping everywhere
Organization context flows through requests, jobs, search, and automations.
Sandboxed extensions
Plugins run isolated and scoped, communicating only through a typed channel.
Operating Securely
A few practices keep a deployment healthy:
- Keep secrets in a secret manager: signing keys, service credentials, and API keys should never live in source control or shared config files.
- Scope and rotate API keys: issue per-integration keys, store them securely, and revoke unused ones.
- Review roles regularly: grant the least privilege necessary and audit role assignments.
- Vet plugins: only install plugins you trust, and review the origins they are registered with.