Approvals & Webhooks
When a policy resolves to approval_required, OpenProdkt does not execute the request and returns a
governed approval decision. SDK integrations may wait or poll for resolution; proxy mode never
waits for approval and blocks the original request immediately.
SDK and proxy modes
| Mode | While approval is pending | After approval |
|---|---|---|
| SDK | The SDK may wait for a bounded time, or return approval_id for app-managed polling or webhook handling. | Your app retries with the same operation_id, approval_id, and payload_hash. |
| Proxy | The proxy immediately returns HTTP 403 or gRPC PERMISSION_DENIED; the protected upstream is not called. A CX/orchestrator polls or receives the approval webhook. | The app retries the original request with the same stable operation_id; the client does not need to send approval_id. |
Proxy mode is transparent to business logic. If the request contains a stable operation_id,
OpenProdkt can automatically correlate the retry and consume the approval in a single successful
redemption. This is an approval state transition only. approval_id is optional for the proxy client.
Identical metadata alone cannot distinguish a retry from a separate operation.
A single redemption does not guarantee exactly-once execution by your upstream. If the
authorization response is lost after redemption, OpenProdkt will not redeem that approval again,
and the upstream outcome may be unknown. Make the business operation idempotent using the same
operation_id and reconcile ambiguous outcomes in your application.
Numeric metadata uses exact decimal canonicalization:
100, 100.0, and 1e2 have the same metadata binding. MCP's separate
complete-arguments digest still preserves numeric text. An update that changes
numeric approval canonicalization requires a coordinated approval drain on both
upgrade and rollback; do not rewrite stored hashes or bypass a retry mismatch.
Invalid context blocks a retry before approval redemption, without consuming
the approval.
Proxy challenge
When a proxied request needs approval, /v1/proxy/evaluate returns HTTP 403 immediately, with
Retry-After: 30 and Cache-Control: no-store. The protected upstream is not called. gRPC callers
receive PERMISSION_DENIED. The body contains:
| Field | Value |
|---|---|
code | approval_required |
retry_after_seconds | 30 (seconds; fixed, not configurable) |
grant_ttl_seconds | 120 (seconds; how long an approved operation can be redeemed) |
status_url | /v1/proxy/operations/{operation_id}, where the operation can be polled |
operation_id | Echoed when it matches ^[A-Za-z0-9._:-]{1,128}$; omitted otherwise |
approval_expires_at | When the pending approval expires |
{
"code": "approval_required",
"retry_after_seconds": 30,
"grant_ttl_seconds": 120,
"status_url": "/v1/proxy/operations/refund-2026-001",
"operation_id": "refund-2026-001",
"approval_expires_at": "2026-09-13T11:15:00Z"
}
status_url and operation_id are present only when the operation ID matches the pattern above. The challenge never includes the approval ID or the payload hash. The CX or orchestrator tracks the
approval through polling or webhooks. The application retries the original request with the same
operation_id after approval.
How it works
The SDK flow does not silently replay your business request. Your application owns the retry unless it opts into a bounded SDK wait.
For details on plans and how licensing works, see Licensing & Distribution.
Choose a delivery model
| Option | How it works | Best for |
|---|---|---|
| Async + Webhook (recommended) | SDK apps or the CX/orchestrator receive an approvalId; OpenProdkt sends lifecycle events to a registered webhook endpoint | Backend jobs, agents |
| App-managed retry (SDK) | Your app stores approvalId, a human approves in the Console, your app retries the original operation with the explicit tuple | Web/mobile apps |
| Short wait (SDK) | The SDK blocks for a bounded time polling for resolution, then returns the result or a timeout | Interactive apps |
| Polling (SDK/CX) | The SDK app or CX/orchestrator checks status via GET /v1/approvals/{id} | Integrations without webhooks |
| Transparent proxy | The proxy immediately blocks pending requests; after approval, the app retries the original request with the same stable operation_id | Existing applications behind the proxy |
SDK integrations may wait or poll. Proxy integrations never wait for approval: they block immediately and rely on the CX/orchestrator to observe resolution before the request is retried.
Async + Webhook
For SDK flows, your application receives the approval ID in the challenge. For proxy flows, the
CX/orchestrator owns the approval handle; the protected application does not need it.
Register a webhook endpoint from the Console (Settings → Webhooks) or via
POST /v1/webhooks, with a URL and the event types you want: approval.pending,
approval.approved, approval.rejected, approval.expired, approval.revoked. Each delivery includes a stable
eventId in the body and X-OpenProdkt-Event-Id header, plus an
X-OpenProdkt-Timestamp header. Verify X-OpenProdkt-Signature using the endpoint secret shown
once at creation. During secret rotation, configure the receiver to accept both the previous and
new secret until in-flight deliveries have drained. The versioned format is v1=sha256=<hex HMAC-SHA256> over the timestamp,
an ASCII period, and the exact raw request body. Enforce a replay window on the timestamp and
durably deduplicate on event ID before handling the event. The bundled SDKs accept timestamps within 5 minutes (Go) or 300 seconds (Python and TypeScript).
App-managed retry
This explicit mode is for SDK integrations whose application manages the approval workflow.
Store the operation_id, approvalId, payload_hash, and the exact asset identity and
authorization context returned by the initial approval_required decision. When a reviewer
resolves it in the Console (or your webhook fires), retry /v1/evaluate with the same
operation_id, asset, transport, and metadata, plus the original approval_id and
payload_hash:
{
"version": "v1",
"asset": { "id": "ast_e8f1a2c3" },
"operation_id": "refund-2026-001",
"approval_id": "apr_5c6d7e8f",
"payload_hash": "sha256:<hash returned by the initial decision>",
"transport": { "kind": "http" },
"metadata": { "operation": "refund", "amount": 9000 }
}
OpenProdkt recomputes the canonical payload hash and checks the organization, authenticated
principal, operation, asset, transport, metadata, and policy revision binding. A changed
context is rejected rather than treated as a new authorization. A pending approval remains
pending; the first valid approved retry atomically redeems it and returns allow. Later attempts
report the consumed status and do not authorize again. Rejected, expired, revoked, unknown, or
mismatched approvals do not authorize the operation. The application must still make the business
operation idempotent using the same operation_id to handle an ambiguous upstream result.
Transparent proxy retry
Proxy mode is transparent to business logic. If the request contains a stable operation_id,
OpenProdkt can automatically correlate the retry and consume the approval in a single successful
redemption. This is an approval state transition only, not upstream execution. approval_id is
optional for the proxy client. The CX/orchestrator polls the
approval or receives its webhook; the protected application does not wait and does not need to
know the approval ID. After approval, it resends the original request through the proxy with the
same operation_id and authorization context. The proxy immediately blocks while approval is
pending and never holds the original request open.
A single redemption is not exactly-once upstream execution. If the authorization response is
lost after redemption, the approval cannot be redeemed again and the upstream outcome may be
unknown. Make the business operation idempotent with the same operation_id and reconcile
ambiguous outcomes. Without a stable operation_id, a matching request fingerprint alone is not
enough to redeem an approval.
Short wait (SDK)
SDKs expose an opt-in bounded wait — see SDK Manual — that polls internally and returns either the resolved decision or a timeout. This never replaces async delivery; it's for interactive UX where a user is actively waiting.
Polling (SDK/CX)
GET /v1/approvals/{id} returns the current status of a single approval. SDKs expose
get_approval_status() (Python), GetApprovalStatus() (Go), and getApprovalStatus()
(TypeScript) for this scoped lookup; polling reads one approval and does not list or reevaluate
requests. API keys must include the approvals:read scope. A decision-only key receives a
403 with code=insufficient_scope; the SDK reports this as a typed scope error rather than a
PDP outage. Async delivery remains the recommended default.
An authorized reviewer (a user JWT with the super_admin or user role) may revoke a pending or approved approval with
POST /v1/approvals/{id}/revoke. Revocation records revokedAt, clears any unconsumed grant,
and emits approval.revoked; later explicit retries remain denied.
Review in the Console
Approvers review requests under Approvals in the Console. Each request shows its asset, requester ID, operation, policy, status, creation and expiry times, and, once resolved, the reviewer and comment. For an MCP tool call, the request also shows the MCP server and tool name. From a request you can:
- Approve or reject, with an optional comment. Only super admins and the owner of the asset can act on it.
- Open View decision to see the policy evaluation for the request.
- Open View audit history to see the audit events recorded for it.
Each request also shows Oversight indicators: how long review took, how long a pending
request has been waiting, whether the reviewer differs from the requester, whether a review
comment is present, and whether it expired without review. These are factual values from stored
approval data when you load the page. They are not a quality score, a risk rating or sealed
evidence, and a value that is not stored is simply not shown. The API returns the same values in
an additive oversight object on GET /v1/approvals and GET /v1/approvals/{id}; the comment
text is never part of it.
The decision and its audit event are recorded together, so a resolved request always has an audit entry.
Email notifications
When a request requires approval, OpenProdkt sends an email to the approvers listed on the asset's group and to the organization's super admins and owners. Each address receives one email. If the asset has no group, only the super admins and owners receive it.
A group approver who is not a super admin or organization owner, and who does not own the asset, receives the email but cannot approve or reject the request in the Console. Approving by group membership is not yet available.
The email summarizes the request: the asset, the requester ID, the operation, the policy, the expiry time, the organization, the approval ID, and the decision ID. For an MCP tool call, it also names the MCP server and tool. When the Console address is configured, it also includes a link that opens the request in the Console.
- The email does not approve or reject the request. Recipients sign in to the Console with the one-time email code and act there.
- The link points to the request in the Console. Users see only the requests their role allows them to review. If you are signed out, sign in first, then open Approvals to find the request.
- Operators set the Console address on the worker with
OPK_CONSOLE_BASE_URL, for examplehttps://console.example.com. It must be an absolutehttporhttpsURL without a query string or fragment. When it is not set, the email has no link and asks the recipient to open Approvals in the Console.
Redemption, expiry, and retry rules
| Item | Value | Configurable |
|---|---|---|
| Pending approval lifetime | 24 hours from creation | No |
| Grant window after approval | 2 minutes (grant_ttl_seconds = 120) | No |
| Effective redemption deadline | The earlier of the grant window end and the approval expiry | No |
| Proxy retry hint | Retry-After: 30 seconds | No |
| In-flight claim on an operation | 5 minutes, after which another request with the same operation ID can take over | No |
Redemption is atomic: one approved approval can be consumed once. A retry is accepted only if it matches the original request on organization, principal, operation_id, asset identity, and the payload hash. The payload hash is a sha256: digest over a canonical form of the policy revisions in force, the transport context (MCP request and session IDs excluded), and the metadata. If the policies, the asset schema, or the metadata change after the approval was created, the retry returns 409 approval_retry_mismatch; start a new operation.
Only published, active policies participate in these bindings. Publishing a
new revision or archiving a live policy changes the policy set and invalidates
stale retries. Editing an unrelated draft does not change the live policy set.
Adding lifecycle status alone does not change existing approval-hash encoding.
Validation and simulation never redeem or create an approval; a simulated
approval_required result is only a preview.
Retry outcomes use these reasons. Only approval_granted allows the call.
| Reason | Decision |
|---|---|
approval_pending | approval_required |
approval_granted | allow (the approval is consumed) |
approval_consumed, approval_rejected, approval_expired, approval_grant_expired, approval_revoked, approval_not_redeemable | deny |
Approve, reject, and revoke need a user session with an authorized role; API keys receive jwt_user_required. An approver cannot be the requester (self_approval_forbidden). Expiry is applied when approvals or operations are next read, so the approval.expired event can be emitted later than the expiry time.
An approved operation records its decision, not its execution. Report the real result through the operation outcome endpoint so the audit trail shows whether the upstream call ran. The first outcome reported wins; a different later report returns 409 operation_outcome_conflict. See Audit.
Webhook delivery and retries
Webhook delivery is asynchronous and at-least-once.
- Dispatch is off unless the operator sets
OPK_OUTBOX_DISPATCH_ENABLED. Without it, no webhooks, approval emails, or approval lifecycle records are produced. - Each delivery has a 10-second connect timeout and a 10-second overall timeout. Redirects are not followed and no proxy is used. A non-2xx response or a network error counts as a failure.
- Failed events are retried with exponential backoff starting at 1 minute and capped at 1 hour, plus jitter, up to 5 attempts by default. After the last attempt the event is dead-lettered and is not retried again. The operator can change the attempt count and batch size; see Limits and Configuration.
- If several endpoints subscribe to the same event, one failing endpoint can cause redelivery to the others. Receivers must deduplicate on
eventId. - Each request carries
X-OpenProdkt-Event-Id,X-OpenProdkt-Timestamp, andX-OpenProdkt-Signature(v1=sha256=<hex>, an HMAC-SHA256 oftimestamp + "." + bodywith the endpoint secret). Reject timestamps older than your replay window; the SDK helpers use 5 minutes. - The body is
{ eventId, eventType, organizationId, aggregateId, data }. - Destinations are checked after DNS resolution on every attempt. Loopback, private, link-local, and reserved ranges are refused by default, cloud metadata addresses are always refused, and
httpscan be required by the deployment. Self-hosted operators can opt specific ranges in withOPK_WEBHOOK_ALLOWED_CIDRS.
Approval scope
An approval is never a permanent permission — it's scoped to a single request:
- Asset — what the request was about
- Policy — which rule triggered the review
- Request/context — the metadata submitted with the decision
- Requester — who or what made the call
- Expiration — pending approvals expire 24 hours after creation and move to
expired. An approved approval is redeemable within a 2-minute grant window (grant_expires_at); a redemption after that window is refused - Status —
pending,approved,rejected,expired,revoked, orconsumedafter one successful redemption
{
"id": "apr_5c6d7e8f",
"decisionId": "dec_9f2a1c4e",
"assetId": "invoice-agent",
"policyId": "pol_8a1b2c3d",
"requesterId": "key_4f5e6d7c",
"status": "pending",
"expiresAt": "2026-09-13T11:15:00Z"
}
See API Reference for the full approvals and webhooks endpoint list, and SDK Manual for language-specific helpers.