Kontxt TxToken integration

Orka can participate in kontxt transaction-token workflows without storing raw transaction tokens in Task specs/status, labels, annotations, logs, metrics, or durable memory. Delegated raw TxTokens are stored only in owner-referenced Kubernetes Secrets for worker handoff. The integration is intentionally staged so existing Kubernetes ServiceAccount and OIDC callers continue to work unless context-token authentication or authorization is explicitly configured.

New to Kontxt or setting it up for the first time? Start with Kontxt quickstart: use Kubernetes identity to call Orka without long-lived tokens, then return here for detailed configuration and security guidance.

Capability summary

Capability	Status
Ingress TxToken verification	Enabled when --context-token-profile=kontxt, issuer, and audience are configured. Tokens are read from Txn-Token by default.
Request-level authorization	Optional off, audit, or enforce mode. Scopes authorize API, chat, provider, tool, memory, session, skill, and security-scan operations. Selected signed tctx values constrain task, provider, model, workspace, and tool requests.
Verified requester stamping	REST-created Tasks record verified identity in immutable spec.requestedBy.
Safe transaction metadata	REST-created context-token Tasks record immutable spec.transaction plus safe transaction labels/annotations; Jobs, Pods, and worker environment receive the same safe metadata.
Immutable delegation chains	Worker-side delegation can exchange a parent TxToken for a child TxToken through kontxt TTS. The requested child scope must be a subset of the parent transaction scopes before Orka creates the child Task.
Downstream token propagation	Worker HTTP Tool calls can propagate a mounted TxToken or exchange it for an operation-scoped outbound TxToken before calling downstream services.
Direct Kubernetes hardening	Optional Task provenance admission webhook rejects untrusted spoofing of Orka-managed provenance fields.
Observability	Prometheus metrics cover context-token authentication, authorization decisions, and TTS exchange health. CLI task/audit commands can correlate work by transaction ID. Logs use safe transaction fields and must not include raw tokens.

Downstream services still need to validate incoming TxTokens themselves. Orka can verify, authorize, exchange, persist safe metadata, and propagate TxTokens inside its control-plane/worker model; it does not transparently enforce mesh-wide policy for arbitrary services.

How Orka maps to the kontxt model

kontxt TxTokens are useful for three platform capabilities, all of which Orka supports when the relevant authz/TTS settings are enabled:

1. Request-level authorization across service boundaries — Orka validates signed TxTokens, evaluates required operation scopes, and uses selected signed tctx fields such as namespace, task type, agent, workspace repo/branch/ref, provider, model, and allowed tools as request constraints.
2. Immutable delegation chains with non-expanding scope — Orka preserves the transaction ID across parent/child Tasks, exchanges mounted subject tokens through kontxt TTS for child or outbound TxTokens, rejects requested child scopes that are not present in the parent transaction scopes, and stores raw child tokens only in owner-referenced Kubernetes Secrets.
3. End-to-end audit correlation — Orka stamps safe transaction metadata onto Tasks, Jobs, Pods, worker environment, and CLI views so operators can follow one transaction ID without storing raw TxTokens or full tctx/rctx payloads.

Subject-token sources for kontxt TTS

Orka validates the resulting kontxt TxToken. The original identity token is validated by kontxt TTS before Orka sees the request. Common subject-token sources include:

Source	Use when	Notes
Kubernetes projected ServiceAccount tokens	In-cluster workloads need TxTokens without an external OIDC issuer.	Kubernetes issues the subject JWT; kontxt TTS must trust the Kubernetes issuer/JWKS. Use bound, audience-scoped projected tokens rather than legacy long-lived ServiceAccount Secret tokens.
GitHub Actions OIDC	CI workflows need to call Orka without long-lived secrets.	Configure kontxt TTS to trust the GitHub Actions OIDC issuer and exchange the short-lived workflow JWT for a TxToken.
Microsoft Entra Agent ID / Workload ID	Enterprise-managed agents, services, or workloads need governed identity.	Use a TTS-specific audience and map stable Entra claims to allowed Orka scopes and signed tctx.
Other OIDC/JWT issuers	Your organization already has a trusted issuer.	Works when kontxt TTS can validate issuer, audience, signing keys, and policy claims.

For Kubernetes, keep the distinction clear: direct ServiceAccount bearer authentication to Orka proves caller identity, but it does not provide kontxt transaction ID, signed tctx, scope narrowing, child TxTokens, or transaction audit correlation. The kontxt flow is projected ServiceAccount token → kontxt TTS → TxToken → Orka.

Kubernetes ServiceAccount token trust

When Kubernetes projected ServiceAccount tokens are used as kontxt TTS subject tokens, TTS must validate the token issuer, audience, expiry, and signing key before issuing a TxToken. Use bound projected tokens with a TTS-specific audience and short expiration; do not rely on legacy long-lived ServiceAccount Secret tokens.

The ServiceAccount issuer is the iss value from the cluster's OIDC discovery document, and TTS needs a reachable discovery/JWKS endpoint for that issuer. In public or centrally managed clusters, prefer a stable issuer URL whose JWKS endpoint is reachable from TTS and handles key rotation normally. In private clusters or Azure Kubernetes Service-style environments where the advertised issuer/JWKS is not reachable from the TTS Pod, use one of these production-safe approaches:

• make the issuer/JWKS endpoint reachable with the correct CA trust;
• expose a managed discovery proxy that preserves the real issuer value and refreshes JWKS as keys rotate;
• configure equivalent static trust settings in TTS only when your operational process refreshes keys before rotation breaks validation.

A static in-cluster mirror of the current discovery and JWKS documents can unblock smoke tests, but it snapshots signing keys. Refresh it after key rotation and avoid treating it as the production design.

Ingress verification

Enable the built-in kontxt profile with issuer and audience:

ORKA_CONTEXT_TOKEN_PROFILE=kontxt
ORKA_CONTEXT_TOKEN_ISSUER=https://kontxt-tts.example.test
ORKA_CONTEXT_TOKEN_AUDIENCE=orka-api
# Optional for kontxt; defaults to <issuer>/.well-known/jwks.json.
ORKA_CONTEXT_TOKEN_JWKS_URL=https://kontxt-tts.example.test/.well-known/jwks.json

By default Orka reads raw TxTokens from Txn-Token:

curl -H "Txn-Token: $TXN_TOKEN" https://orka.example.test/api/v1/tasks

Authorization: Bearer remains reserved for ServiceAccount and OIDC bearer tokens unless context-token bearer support is explicitly opted in:

ORKA_CONTEXT_TOKEN_HEADERS=Txn-Token,Authorization:Bearer

When bearer support is enabled, Orka only treats bearer JWTs with JOSE header typ: txntoken+jwt as context tokens; other bearer tokens continue through OIDC or Kubernetes TokenReview authentication.

Authorization modes

Context-token authorization is disabled by default. Enable it gradually:

# Evaluate and log safe would-deny decisions, but allow requests.
ORKA_CONTEXT_TOKEN_AUTHZ_MODE=audit

# Reject context-token callers that lack scope or violate signed context.
ORKA_CONTEXT_TOKEN_AUTHZ_MODE=enforce

Authorization only applies to authenticated context-token callers. ServiceAccount and OIDC behavior remains backward-compatible unless a request is authenticated as a context token.

Default scopes

Operation class	Default scope
Task create	orka:tasks:create
Task read/get-related data	orka:tasks:get
Task list	orka:tasks:list
Task delete	orka:tasks:delete
Tool read	orka:tools:read
Orka-managed tool use	orka:tools:use
Chat/OpenAI/Anthropic provider use and model listing	orka:providers:use
Agent read/write	orka:agents:read / orka:agents:write
Memory read/write	orka:memory:read / orka:memory:write
Session read/write-delete	orka:sessions:read / orka:sessions:write
Security scan read/write	orka:security:read / orka:security:write
Repository monitor read/write/operate	orka:monitors:read / orka:monitors:write / orka:monitors:operate
Skill read/write	orka:skills:read / orka:skills:write

Each scope list is configurable with the corresponding ORKA_CONTEXT_TOKEN_*_SCOPES environment variable or --context-token-*-scopes flag. Use comma-separated values when allowing aliases.

Signed tctx constraints

Orka also uses selected signed transaction context values for request-specific checks. Example token context:

{
  "namespace": "default",
  "taskType": "agent",
  "agent": "security-reviewer",
  "allowedAgents": ["security-reviewer", "patcher"],
  "repo": "https://github.com/sozercan/orka",
  "branch": "kontxt",
  "allowedTools": ["file_read", "web_search"],
  "allowedProviders": ["openai"],
  "allowedModels": ["gpt-5.4"]
}

In enforce mode Orka rejects context-token requests whose body or resolved route violates these constraints, for example a mismatched namespace, agent, repository, provider, model, or tool set. In audit mode the same policy is evaluated and logged with safe fields, but the request is allowed.

Safe transaction metadata

When a REST request creates a Task with a valid context token, Orka stamps:

• immutable spec.requestedBy with verified subject/issuer/roles;
• immutable spec.transaction with safe transaction metadata;
• labels such as orka.ai/transaction-id and orka.ai/auth-profile;
• annotations such as orka.ai/transaction-id, orka.ai/transaction-scope, orka.ai/transaction-context-digest, and orka.ai/requester-context-digest.

The controller propagates safe metadata to Jobs, Pod templates, and worker environment variables including:

ORKA_TRANSACTION_ID
ORKA_TRANSACTION_PROFILE
ORKA_TRANSACTION_ISSUER
ORKA_TRANSACTION_SUBJECT
ORKA_TRANSACTION_REQUESTING_WORKLOAD
ORKA_TRANSACTION_SCOPE
ORKA_TRANSACTION_SCOPES
ORKA_TRANSACTION_CONTEXT_DIGEST
ORKA_TRANSACTION_REQUESTER_CONTEXT_DIGEST

Raw TxTokens are not stored in Task specs/status, labels, annotations, logs, or metrics. Full tctx and rctx are treated as sensitive; Orka stores digests and selected allowlisted string context fields only.

TTS exchange, delegation, and outbound propagation

Orka has two token-flow patterns:

1. Propagate an existing child token: if a Task annotation references an Orka-owned transaction-token Secret, the controller mounts it into the worker and sets both ORKA_TRANSACTION_TOKEN_FILE and ORKA_CONTEXT_TOKEN_SUBJECT_TOKEN_FILE to the token path. HTTP Tool calls attach that token as Txn-Token.
2. Exchange a replacement token through TTS: when worker environment includes a TTS URL, subject-token file, and requested child/outbound scope, worker-side delegation tools and HTTP Tool calls call kontxt TTS for a child or operation-scoped replacement token before creating child Tasks or calling downstream services.

Worker-side exchange environment:

ORKA_CONTEXT_TOKEN_TTS_URL=https://kontxt-tts.kontxt-system.svc
ORKA_CONTEXT_TOKEN_SUBJECT_TOKEN_FILE=/var/run/orka/transaction-token/token
# Optional; defaults to urn:ietf:params:oauth:token-type:txn_token.
ORKA_CONTEXT_TOKEN_SUBJECT_TOKEN_TYPE=urn:ietf:params:oauth:token-type:txn_token
# Required for delegate_task/create_container_task exchanges.
ORKA_CONTEXT_TOKEN_CHILD_SCOPE=orka:agents:run
# Optional for HTTP Tool exchanges; falls back to ORKA_TRANSACTION_SCOPE.
ORKA_CONTEXT_TOKEN_OUTBOUND_SCOPE=orka:tools:use

Delegation scope is fail-closed: a requested child scope must be a subset of the parent Task transaction scopes. A successful child-token exchange stores the returned raw TxToken only in an owner-referenced Kubernetes Secret so the child worker can mount it; the Task stores only the Secret reference annotation and safe transaction metadata.

Controller/API TTS flags are available for deployments that configure Orka-side exchange plumbing. When a child Task mounts an Orka-owned transaction-token Secret, the controller propagates the TTS URL and worker exchange scope settings into that child worker so deeper delegation can request narrower replacement tokens:

ORKA_CONTEXT_TOKEN_TTS_URL=https://kontxt-tts.kontxt-system.svc
ORKA_CONTEXT_TOKEN_TTS_AUDIENCE=orka
ORKA_CONTEXT_TOKEN_TTS_TIMEOUT=5s
ORKA_CONTEXT_TOKEN_TTS_TOKEN_SOURCE=serviceAccount
ORKA_CONTEXT_TOKEN_SUBJECT_TOKEN_TYPE=urn:ietf:params:oauth:token-type:txn_token
ORKA_CONTEXT_TOKEN_CHILD_SCOPE=orka:agents:run
ORKA_CONTEXT_TOKEN_OUTBOUND_SCOPE=orka:tools:use
ORKA_CONTEXT_TOKEN_CHILD_TOKEN_TTL=5m
ORKA_CONTEXT_TOKEN_TOOL_TOKEN_TTL=2m

These settings do not by themselves grant downstream access; workers still need an appropriate subject token file, which Orka provides automatically only for Tasks with an owner-referenced transaction-token Secret.

Direct Kubernetes provenance hardening

The REST API rejects client-supplied spec.requestedBy and spec.transaction and stamps verified provenance itself. To prevent direct Kubernetes API users from spoofing the same fields, enable the optional validating admission webhook:

ORKA_TASK_PROVENANCE_ADMISSION_ENABLED=true

The webhook rejects untrusted creates or updates that set or modify:

• spec.requestedBy
• spec.transaction
• orka.ai/transaction-* labels and annotations
• orka.ai/context-token-profile
• orka.ai/transaction-token-secret

Trusted controller/API ServiceAccounts and the worker ServiceAccount are configurable with ORKA_TASK_PROVENANCE_ADMISSION_TRUSTED_USERS and ORKA_TASK_PROVENANCE_ADMISSION_TRUSTED_SERVICE_ACCOUNTS.

Observability

Context-token metrics use low-cardinality labels only:

Metric	Labels	Meaning
orka_context_token_auth_total	profile, result	Context-token authentication successes/failures.
orka_context_token_authorization_total	action, result, reason	Authorization decisions such as allowed, denied, or audit-mode would-deny.
orka_context_token_tts_exchange_total	result, reason	TTS exchange attempts.
orka_context_token_tts_exchange_duration_seconds	result, reason	TTS exchange latency.

Use logs and safe annotations for per-transaction tracing. The CLI can filter Task summaries by transaction ID:

orka task list --transaction txn-abc123
orka task get my-task --show-transaction
orka audit trace txn-abc123

Do not use raw transaction IDs, subjects, repositories, task names, or token values as metric labels.

Redaction rules

Never commit, log, print, or persist raw TxTokens in Task specs/status, labels, annotations, durable memory, artifacts, metrics, or docs. The only Orka-managed storage location for delegated raw TxTokens is an owner-referenced Kubernetes Secret used for worker handoff. Orka redaction covers Txn-Token and Authorization header values plus token-looking strings in worker/tool output. Keep downstream tools and custom scripts under the same rule: log transaction IDs and digests, not tokens.

Example least-privilege Task token

A token that can create one agent Task in default, bound to a repository/branch and a narrow tool set, would use a scope and context like:

{
  "scope": "orka:tasks:create orka:tools:use",
  "tctx": {
    "namespace": "default",
    "taskType": "agent",
    "agent": "coder",
    "repo": "https://github.com/sozercan/orka",
    "branch": "kontxt",
    "allowedTools": ["file_read", "file_write"]
  }
}

Start in audit mode to observe missing scopes and context mismatches, then switch to enforce once callers consistently issue least-privilege TxTokens.