Security Model
ProvenanceOne's security model is built on four layers: identity and access control (the identity service + RBAC + API key scopes), runtime data protection (MCP Gateway DLP, encryption at rest and in transit), auditability (immutable platform key management-signed audit log with 7-year retention), and data subject rights (GDPR erasure). This page summarises each layer and links to deeper references.
When to use this page
Read this page to understand the security architecture before deploying ProvenanceOne in a regulated or enterprise environment, when scoping API key permissions for an integration, or when responding to a security questionnaire.
Key concepts
Authentication — all platform API endpoints (except webhook inbound and bus inbound) require either a JWT Bearer token issued by the platform identity service or a workspace API key passed in the x-api-key header. Webhooks and bus inbound endpoints are authenticated with HMAC-SHA256 signatures.
RBAC — three roles govern what humans can do in a workspace: admin, editor, and viewer. Roles map to platform groups: workspace-admins, operators, and viewers. A separate approvers group covers approval-specific permissions.
API key scopes — workspace API keys carry one or more of 16 named scopes. A key without a scope cannot access the corresponding resource, even if issued by an admin.
MCP Gateway — all MCP tool calls from agents are proxied through the MCP Gateway. Gateway policies define which tools an agent is allowed or denied and can apply input/output redaction rules. This is the primary DLP control for agent runtime behaviour.
Audit immutability — every audit event carries a HMAC-SHA256 MAC field. The MAC is computed server-side at event creation time and cannot be retroactively altered. This field serves as evidence of log integrity.
How it works
Authentication flow
- Users authenticate via the identity service and receive a JWT access token.
- The JWT is passed in the
Authorization: Bearerheader on every API request. - The platform validates the JWT signature, expiry, and workspace membership before serving the request.
- For programmatic integrations, workspace API keys are created in Settings with specific scopes. API keys are passed in
x-api-key. - OAuth 2.0 is used for connection authorisation flows (Slack, GitHub, etc.) — not for platform API authentication.
Role-based access control
| Operation | admin | editor | viewer |
|---|---|---|---|
| Manage members and roles | Yes | No | No |
| Billing and workspace settings | Yes | No | No |
| Create / edit / delete workflows | Yes | Yes | No |
| Publish workflows | Yes | Yes | No |
| Trigger runs | Yes | Yes | No |
| Approve / reject approvals | Yes | Yes | No |
| View runs and audit log | Yes | Yes | Yes |
| Create / edit agents and skills | Yes | Yes | No |
| Create / edit connections | Yes | Yes | No |
| Reveal secrets | Yes | No | No |
| Create / revoke API keys | Yes | No | No |
| GDPR member erasure | Yes | No | No |
| Manage environments | Yes | No | No |
API key scopes
All 16 available scopes:
| Scope | Access granted |
|---|---|
workflows:read | List and get workflows |
workflows:write | Create, update, publish, delete workflows |
runs:read | List and get runs and steps |
runs:write | Trigger, cancel, replay runs |
approvals:read | List and get approvals |
approvals:write | Approve, reject, reassign approvals |
agents:read | List and get agents |
agents:write | Create, update, delete agents |
skills:read | List and get skills |
skills:write | Create, update, delete skills |
connections:read | List and get connections |
connections:write | Create, update, delete connections |
audit:read | Read audit events |
workspace:read | Read workspace settings and members |
workspace:write | Update workspace settings and members |
secrets:read | Reveal secrets (high-risk, always audited) |
Warning: The
secrets:readscope grants the ability to reveal raw secret values viaPOST /secrets/{id}/reveal. Every reveal is logged as a high-risksecret.accessedevent. Issue this scope only to integrations that genuinely require it.
MCP Gateway as DLP control
Every tool call made by an agent is routed through the MCP Gateway before it reaches the target MCP server. The gateway evaluates the call against:
- Tool allow/deny lists — per-agent or per-workspace policies that permit or block specific tools
- Input redaction — regular-expression or JSONPath rules that redact sensitive patterns (e.g. PII, card numbers) from tool inputs before they are sent
- Output redaction — equivalent rules applied to tool responses before they reach the agent
Gateway policy changes are audited as gateway_policy.created, gateway_policy.updated, and gateway_policy.deleted. Policy violations emit policy.violation events.
Encryption
| Data | Encryption |
|---|---|
| Data at rest (datastores) | platform-managed server-side encryption at rest |
| Data at rest (secrets) | the secrets vault with platform-managed key |
| Data at rest (platform database tables) | encryption at rest |
| Data in transit | TLS 1.2+ on all endpoints |
| Approval task tokens | encrypted before storage |
| Audit event MAC | HMAC-SHA256 |
Audit immutability
Every audit event is written with a mac field computed as a HMAC-SHA256 digest over the canonical event body. The MAC is stored alongside the event in platform database. To verify an event has not been tampered with, recompute the MAC using the same platform key management key and compare. Events are retained for 7 years (configurable TTL per workspace but the floor is 7 years for compliance).
See /docs/audit for the full event taxonomy and digest configuration.
GDPR
ProvenanceOne provides a GDPR member erasure endpoint: POST /workspace/members/{userId}/erase. This operation:
- Removes the member from the workspace
- Emits a
member.erasedevent (risk:critical) - Replaces the
personIdfield in all historical audit events for that user with a tombstone value
After erasure, audit events that referenced the member retain their actorId and event data but the personally identifying personId field is erased. This allows audit integrity to be maintained while satisfying the right to erasure.
Only admin role can perform erasure.
Webhook and bus inbound authentication
Webhooks (inbound to POST /webhooks/{workflowId}) and bus inbound messages (POST /bus/inbound/{subscriptionId}) do not use JWT or API key authentication. They are authenticated with HMAC-SHA256 signatures. The external system signs the request body with a shared secret and includes the signature in the request headers. The platform validates the signature before processing the payload.
Note: If an inbound request fails HMAC validation, it is rejected with
401and the event is not emitted.
Configuration options
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| API key scopes | array | Yes | — | One or more of the 16 scope strings |
| dataRetentionDays | integer | No | — | Workspace-level data retention in days |
| Gateway policy — tool allow | array | No | — | List of tool names/patterns to allow |
| Gateway policy — tool deny | array | No | — | List of tool names/patterns to deny |
| Gateway policy — input redaction | array | No | — | JSONPath or regex rules for input scrubbing |
| Gateway policy — output redaction | array | No | — | JSONPath or regex rules for output scrubbing |
Examples
Create a read-only API key for an audit integration
In Settings → API Keys, create a new key with only the audit:read scope. Pass this key as x-api-key in requests to GET /audit.
Block a specific MCP tool across the workspace
In Settings → MCP Gateway, create a gateway policy with:
effect:denytool:file_deletescope: workspace
Any agent that calls file_delete will have the call blocked and a policy.violation event emitted.
Common mistakes
- Issuing API keys with wildcard or overly broad scopes. Prefer the minimum set of scopes the integration needs. Audit this periodically.
- Skipping the MCP Gateway configuration. Without gateway policies, agents can call any tool their attached MCP server exposes. Add deny rules for destructive tools in production.
- Not revoking API keys when a team member leaves. API keys are not tied to a user session. Revoke keys in Settings when access should end.
- Confusing
editorandadminfor approval workflows. Both roles can approve runs but onlyadmincan change workspace settings and manage members.
Troubleshooting
401 Unauthorized on all API calls — confirm the Authorization: Bearer header contains a valid, non-expired platform JWT, or that x-api-key contains a valid workspace API key. JWTs expire; refresh the token via the identity service auth flow.
Agent is calling tools it should not have access to — check the MCP Gateway policies for that agent. Ensure a deny rule is in place. Policy changes take effect on the next run.
403 Forbidden on a specific endpoint — the JWT or API key is valid but lacks the required scope or role. Check the required scope in the API reference and update the key's scope list in Settings.
Related pages
FAQ
What encryption does ProvenanceOne use?▾
Credentials in the secrets vault and approval task tokens are encrypted using platform key management. All data in transit uses TLS 1.2 or higher via the API layer. Audit event integrity is cryptographically protected by a HMAC-SHA256 MAC field on every event record. Full encryption configuration (object storage, platform database at-rest settings) requires product confirmation.
How do I restrict what an agent can do?▾
Use MCP Gateway policies to allow or deny specific tools, and to apply input/output redaction rules. Gateway policies are evaluated before every tool call. You can also use approval steps in the workflow DAG to require human sign-off before high-impact actions proceed.
Can I export audit logs?▾
Yes. Use `GET /audit` with the `audit:read` scope to retrieve events programmatically. You can filter by event type, actor, risk level, and date range. The audit digest feature also sends scheduled email summaries (daily, weekly, or monthly) to configured recipients. See the Audit Log page for details.
What is the minimum role to approve a workflow run?▾
Both `editor` and `admin` roles can approve and reject approval steps in workflow runs. `viewer` cannot approve. If you need fine-grained approval delegation, use the delegated grants feature which allows an `editor` or `admin` to pre-approve specific run patterns.