Knowledge Entitlements

Technical reference. This page is for integrations, advanced configuration, or platform operations. For portal tasks, start with the user guide.

Knowledge-base retrieval is user-bound. Runtime-gateway evaluates the bound knowledge access contract against the execution subject before it queries the retrieval service.

The retrieval service also enforces a data-plane guard. /v1/query requires:

• the internal service token
• a short-lived signed retrieval authorization decision
• a decision whose knowledge base and version match the query payload

Runtime-gateway signs that decision after entitlement evaluation. Direct service-auth callers without the signed decision receive 403.

Access contract shape

Knowledge entitlements are stored inside the immutable knowledge_base asset version content under access_contract. The contract is deny-by-default and is evaluated before retrieved chunks can be attached to a model call.

Common fields are:

Malformed, missing, or revoked contracts fail closed. The runtime also disables memory replay/writeback for that execution when the bound knowledge contract is not usable, so restricted context does not leak indirectly through memory.

Revalidation boundaries

Entitlement revocation is versioned and revalidated at three boundaries:

1. the run-start knowledge-contract snapshot
2. a fresh control-plane read at every retrieval mint
3. retrieval-service verification (TTL ≤ 300s, single-use nonce)

A mid-run revoke or content drift denies the next retrieval step as entitlement_stale or contract_revoked. The residual exposure is one already admitted in-flight query; copies of retrieved content are a later concern.

Engine-path retrieval also requires a release-bound policy decision. A release that binds a knowledge base but no policy bundle is denied policy_decision_missing. Bind a permitting bundle before deploying.

The playground knowledge-assistant release stamps playground-safety-policy as its policy bundle for new databases. Existing playground databases need make playground-reset, which wipes playground state. The playground flow’s retrieve_documents task step is not a retrieval plugin; governed retrieval runs through the engine retrieval step / handle_retrieval path.

Knowledge entitlements decide whether a workload may retrieve from a knowledge base. Context recall policy and the budget planner decide which governed memory and context segments may enter the prompt after that entitlement check. Use Context Budget Planner for workspace and workload context policy, request overrides, diagnostics, and token allocation.

Operator Settings

Retrieval authorization decisions are signed with the querying workspace’s own key from the reserved retrieval-HMAC key family in Vault, not with a value an operator sets. There is no shared signing secret: a decision minted for one workspace cannot be verified against another’s key, so a compromise of one workspace’s material does not reach any other workspace’s knowledge.

Each process reaches its key through its own purpose AppRole credential, projected as a directory that is re-read on every login so a rotation is a file replacement rather than a restart:

ORQESTRA_RETRIEVAL_HMAC_CREDENTIAL_DIR=/run/orqestra/retrieval-hmac

Required outside local development on runtime-gateway, the runtime executor and retrieval-service. A process without it cannot sign or verify a single retrieval decision, so readiness fails closed rather than serving traffic that would be denied at the boundary.

Revoking access

Workspace admins can revoke a knowledge entitlement after a workload has been released, without requiring a re-release.

When to revoke

• Compliance review — a knowledge base contains data that a workload should no longer access.
• Incident response — immediately block all retrieval for a specific contract.
• Access re-evaluation — the operator decides the workload no longer needs the knowledge base.

How it works

Revoking sets revoked=true on the access contract. The runtime gateway re-reads the contract before every execution, so the next execution attempt sees the revoked state and denies retrieval. Pre-issued retrieval-authorization tokens (300s TTL) remain technically valid at the retrieval-service level, but the runtime gateway refuses to use them once it sees the revoked contract.

Portal

Navigate to Administer → Access & org → Knowledge Entitlements for a cross-workload view, or use the inline Revoke button on any workload’s detail page. A confirmation modal collects the required reason. The Access & org path needs namespace administration (namespace.manage); the per-workload Revoke button stays available without it.

CLI

orqestractl knowledge entitlement list
orqestractl knowledge entitlement revoke <contract_id> --reason "compliance review"
orqestractl knowledge entitlement unrevoke <contract_id> --reason "re-evaluated after review"

API

curl "http://localhost:8000/v1/knowledge-entitlements?revoked=false&limit=50&offset=0"

curl -X POST "http://localhost:8000/v1/knowledge-entitlements/$CONTRACT_ID:revoke" \
  -H "Content-Type: application/json" \
  -d '{"reason": "compliance review"}'

curl -X POST "http://localhost:8000/v1/knowledge-entitlements/$CONTRACT_ID:unrevoke" \
  -H "Content-Type: application/json" \
  -d '{"reason": "re-evaluated after review"}'

The list endpoint returns items and total. Results are filtered to workspaces the actor can read and can be filtered by revoked state.

SDK

async with OrqestraClient(base_url=url, api_key=key) as client:
    page = await client.knowledge_entitlements.list(revoked=False)
    await client.knowledge_entitlements.revoke(
        "contract-support-docs",
        reason="compliance review",
    )

The SDK raises an entitlement-state conflict when a revoke request targets an already revoked contract or an unrevoke request targets an already active contract.

Un-revoking

Un-revoke restores access. Both transitions are recorded in the governance audit chain with full before/after state and the operator’s justification.

Denial Audit

When the runtime gateway denies retrieval (revoked contract, missing entitlement, or malformed access contract), it appends a v1.governance.knowledge_entitlement_denied row to the hash-chain audit trail. The row records the execution subject and resource context without leaking the user query. If the audit-chain append itself fails, the execution fails closed with a 5xx rather than silently degrading to flat logs.

Evidence

Execution detail responses and portal evidence views expose the execution subject fields: execution mode, actor ref, actor type, actor auth mode, and principal access mode.

Troubleshooting