Access Control & Audit

How Oxagen gates capability calls with workspace-scoped ACL grants and records every invocation in an append-only audit trail.

Every read, write, generation, and external call in Oxagen runs through a single dispatch path: the capability registry. The registry checks an Access Control List (ACL) before it runs the handler, then writes a row to the audit trail when the call completes. The same checks apply whether the caller is a user in the web app, an API client with a bearer token, an MCP client, or an agent acting on a workspace.

Capabilities are the unit of permission

A capability is a typed function exposed by the platform (e.g. ontology.search, docs.create_from_spec, external.salesforce.upsert). Each capability declares a kind that describes what it does:

Kind	What it does	Default policy
`read`	Pure read against workspace state. Idempotent.	Any tenant member, no grant required
`write`	Mutates graph nodes, edges, types, memory, or agent state.	Requires grant (OWNER role allowed)
`generate`	Invokes an LLM or other generative model.	Requires grant
`external_io`	Calls a third-party service (Gmail, Drive, Stripe, etc.).	Requires grant
`dispatch`	Schedules background or asynchronous work.	Requires grant

This taxonomy is the floor. ACL grants override the defaults in either direction — you can deny a read to a specific user, or allow a generation capability to an agent role.

ACL grants

A grant lives on a single workspace and binds three things together:

(workspace, principal, capability pattern)  →  allow | deny

Field	What it means
`workspace_id`	The workspace the grant applies to. Grants do not cross workspaces.
`principal_kind`	`user`, `tenant_role`, `agent_definition`, or `any_member`. Determines how the principal is matched.
`principal_id`	The user UUID, when `principal_kind` is `user`. Null otherwise.
`principal_role`	The role name (`OWNER`, `MEMBER`) or agent slug, depending on kind. Null when not applicable.
`capability_glob`	A glob pattern that matches one or more capabilities. Examples: `ontology.read`, `docs.`, `external.salesforce.`.
`effect`	`allow` or `deny`.
`expires_at`	Optional UTC timestamp. After it passes, the grant stops matching.
`granted_by_id`	The user who created the grant.

Principal kinds

`principal_kind`	Matches
`user`	A single authenticated user, identified by UUID.
`tenant_role`	Every user in the workspace's tenant who holds the named role — `OWNER` or `MEMBER`.
`agent_definition`	Every agent run dispatched under the named agent slug.
`any_member`	Any authenticated user with membership in the workspace's tenant.

Capability globs

Capability patterns use shell glob syntax against the dotted capability name. A grant for docs.* matches docs.create_from_spec, docs.append_to_google_doc, and any future docs.<x> capability. A grant for external.salesforce.upsert matches only that one capability.

ontology.search                    # one capability
docs.*                             # every docs capability
external.salesforce.*              # every Salesforce capability
*                                  # every capability — use sparingly

Decision flow

Each capability call resolves to one decision using a fixed precedence:

The precedence is, top to bottom:

Explicit deny grants — highest priority. One matching deny blocks the call regardless of other allow grants.
Explicit allow grants — any matching allow permits the call.
Role defaults — the tenant role OWNER is granted write capabilities by default. No other role-based defaults apply.
Kind defaults — read capabilities are open to any tenant member; write, generate, external_io, and dispatch capabilities require an explicit grant.

When the call is denied, the response is HTTP 403 on the API surface and an access_denied error in MCP. The reason string from the evaluator is returned to the caller and written to the audit row.

Worked example

A workspace has two ACL grants:

Grant	Effect	Capability glob	Principal
Marketing team can run generation	`allow`	`generate.*`	`tenant_role` = `MEMBER`
External Salesforce writes blocked	`deny`	`external.salesforce.*`	`any_member`

A MEMBER calling generate.image is allowed by grant #1. A MEMBER calling external.salesforce.upsert is denied by grant #2, because explicit deny outranks every other rule. An OWNER calling external.salesforce.upsert is also denied — the deny grant fires for any member, including owners.

Caching and invalidation

The ACL evaluator caches decisions per workspace. When a grant is created, revoked, or updated, the cache for that workspace is invalidated and the next call re-evaluates from the grant table. Grants in other workspaces are unaffected.

Audit trail

The audit trail lives in the dedicated audit schema and is append-only from the application's perspective. There are three tables.

`audit.capability_invocations`

One row per capability call, written by the registry dispatch function. Records timing, status, and credits for every read, write, generation, and external call, regardless of which surface initiated it.

Column	What it holds
`workspace_id`	Workspace the capability was called in.
`user_id`	Authenticated end user, or null for system-initiated calls.
`agent_run_id`	Agent run UUID when the call came from an agent, otherwise null.
`caller`	Surface that initiated the call: `api`, `mcp`, or `app`.
`capability_name`	Dotted capability name (e.g. `ontology.search`).
`capability_kind`	One of `read`, `write`, `generate`, `external_io`, `dispatch`.
`status`	`success`, `error`, `denied`, or `cancelled`.
`error_code`	Machine-readable error code on failures.
`input_hash`	SHA-256 of the canonicalized input JSON.
`output_hash`	SHA-256 of the canonicalized output JSON. Null on error or denial.
`credits`	Credits charged for the invocation.
`latency_ms`	End-to-end latency in milliseconds.
`idempotency_key`	Caller-supplied idempotency key when present.
`is_replay`	`true` when the row represents a cached idempotency hit, not a fresh handler run.
`started_at`	UTC timestamp when dispatch began.
`ended_at`	UTC timestamp when the handler returned. Null when the call was cancelled before completion.

`audit.audit_events`

One row per operator-initiated mutation — sharing changes, credit adjustments, subscription updates, user deactivations. Each row carries the acting user, the action, the target resource, a sanitized payload, the source IP, and the user agent.

Column	What it holds
`actor_user_id`	User who performed the action.
`actor_email`	Denormalized email at time of action — survives a deleted user row.
`action`	Dotted action key (e.g. `content_studio.revoke_public`, `credits.adjust`).
`target_type`	Resource type (`tenant`, `user`, `subscription`, etc.).
`target_id`	UUID of the affected row, or null for catalog-wide actions.
`payload`	Sanitized JSON context. Never contains secrets, tokens, or full PII.
`ip_address`	Source IP from the left-most public hop in the request chain.
`user_agent`	User-Agent header from the originating request.

`audit.ontology_events`

One row per ontology write — node, edge, or type mutations performed by agents or users. Records the event kind (e.g. auto_merge, confirmed_merge, delete_node, rename_type), the actor, the affected resource, and event-specific details (such as kept/dropped IDs for merges or repointed edge counts).

What is not stored

The audit trail records the shape of every call without retaining its content. Inputs and outputs are SHA-256 hashed — the registry never persists raw prompt text, raw document bodies, or third-party API request bodies. The payload field on audit_events is passed through a deny-list scrubber before insert.

This pairs with the broader storage minimization described in Security & Privacy.

Audit writes never fail the business call

Audit log writes run in a nested SAVEPOINT. A failure on the audit insert — for example, a transient database error — is logged but does not roll back the capability handler's transaction. The capability call succeeds or fails on its own merits; the audit row is best-effort and recoverable independently.

Querying the trail

The audit tables are workspace-scoped where applicable and follow the same PostgreSQL Row-Level Security model as the rest of the platform. A workspace can only see its own capability_invocations and ontology_events rows; audit_events is global and gated to staff.

Indexes on the trail tables support the common access patterns:

Capability calls by workspace and time range
Capability calls by workspace and capability name
Operator actions by actor
Operator actions by target resource
Ontology events by workspace and resource

The trail is the system of record for SOC 2 access-control and change- management evidence and is the input to internal compliance review.

Grant lifecycle in practice

When you provision a new agent or a new integration in a workspace, set the minimum grants the agent needs and nothing more. Use tenant_role or agent_definition grants in preference to per-user grants — they survive team changes and are easier to audit. Use deny grants to carve out specific capabilities from a broader allow — for example, allow docs.* but deny docs.share_public.

Set expires_at on grants that exist for a finite reason — a contractor engagement, a one-off backfill, a temporary debug session. Expired grants stop matching automatically and remain in the table for audit history.

Responsible disclosure

Found an access-control or audit issue? Email security@oxagen.ai. Responses go out within 24 hours. Please do not open public GitHub issues for security vulnerabilities.

Access Control & Audit

On this page