[github-actions]

kagent-dev/kagent#3359 — feat(auth): add gateway Actor JWT credentials

Docs versions: 1.x (first shipped in v1.0.0-rc1)

No code-path rule covers 4 touched file(s). The planner could route these only by identifier search, so the candidate pages may miss what they changed, including in the other mode:

• docs/architecture/credential-injection.md
• go/core/internal/controller/remotemcpserver/reconciler.go
• go/core/internal/service/tool/mcp.go
• go/core/internal/translator/egress.go

What changes for users: Operators can set spec.actorJwt on ModelConfig and RemoteMCPServer, or authentication.actorJwt on an EgressPolicy destination, so a downstream service can authenticate the executing Actor instead of the invocation caller. Audiences are required, expirationSeconds defaults to 900, and kagent-runtime is reserved for controller calls.

What the docs now say: The model provider, MCP tools, EgressPolicy, identity, egress, and harness pages now describe Actor JWT credentials, provider support, required audiences, lifetime bounds, credential-field exclusivity, RemoteMCPServer discovery behavior, and EgressPolicy placeholder-header behavior.

Not verified: No cluster; the configuration is unrun.

How kagent-3359 was drafted, and what was not verified

• Code PR: feat(auth): add gateway Actor JWT credentials kagent#3359
• Code issue: none linked
• Product: kagent (upstream) -> kagent-dev/website
• Docs version: 1.x, first shipped in v1.0.0-rc1.
• Category: scoped-edit / pr

Plan, and what changed it

• Planned: Add actorJwt alongside the existing model-provider credential and identity guidance.
• Learned: The unrouted dossier diff and target search showed that RemoteMCPServer and EgressPolicy pages already document the changed credential behavior, so those pages needed edits too.
• Did: Documented Actor JWT credentials on the model-provider, MCP tools, EgressPolicy, identity, egress, harness, Azure OpenAI, and Azure AI Foundry pages.

Why a documentation change is necessary

The pull request adds the actorJwt API surface to ModelConfig, RemoteMCPServer, and EgressPolicy authentication. The existing pages documented Secret-backed credentials and caller-token passthrough, but did not explain how to authenticate the executing Actor to a downstream service. The generated API reference will list the fields, but the prose pages own when to use them and the constraints around provider support, audiences, lifetimes, and mutually exclusive credential choices.

The neighbor dossier for kagent-dev/kagent#3362 says the target version also resolves Agent metadata from scoped Actor tokens. The excerpt did not include a prose-doc target for that follow-up API, so this draft stays on the credential fields that #3359 adds.

What changed on disk

• docs-site/content/kagent/1.x/setup/model-providers/about-model-providers.md: Adds a ModelConfig Actor JWT section, provider support, field constraints, and the credential-header table row.
• docs-site/content/kagent/1.x/setup/model-providers/azure-openai.md: Adds actorJwt to the Azure OpenAI authentication table.
• docs-site/content/kagent/1.x/setup/model-providers/azure-ai-foundry.md: Adds actorJwt to the Foundry authentication table.
• docs-site/content/kagent/1.x/skills-and-mcp/about-tools.md: Adds RemoteMCPServer Actor JWT configuration and discovery behavior.
• docs-site/content/kagent/1.x/agents/egress-policies.md: Adds an EgressPolicy Actor JWT example and validation conflict note.
• docs-site/content/kagent/1.x/about/substrate-runtime/identity.md: Adds downstream Actor JWTs to the identity model.
• docs-site/content/kagent/1.x/about/substrate-runtime/networking-and-egress.md: Updates the credential sources that feed egress policy rules.
• docs-site/content/kagent/1.x/agents/agent-harness.md: Adds the ModelConfig spec.actorJwt provider-support restriction.

How to verify this change

1. Apply a ModelConfig that sets spec.actorJwt.audiences and points a supported provider, such as OpenAI, at a test endpoint that trusts the Agent Substrate issuer.
2. Apply a RemoteMCPServer with spec.actorJwt.audiences; kubectl get remotemcpserver <name> -n <namespace> -o yaml should report DiscoveryDisabled with the message Global tool discovery requires an executing Actor because actorJwt is enabled; agents resolve the tool list at run time.
3. Apply an EgressPolicy with authentication.actorJwt, select it from an Agent, and call the destination from the agent. The downstream service should receive the configured header with a Bearer JWT whose audience matches the configured value.

Proposed release note

No proposed-release-note.md: markers.notes_placeable is false for this item.

Suggested note text: Downstream services can authenticate the executing Actor by using spec.actorJwt on ModelConfig or RemoteMCPServer, or authentication.actorJwt on EgressPolicy destinations. Agent Substrate mints and refreshes the token at the egress gateway; audiences are required, and the lifetime defaults to 900 seconds.

What was not verified

• The configuration was not applied to a cluster, so every command in this diff is unrun.
• Internal links are unchecked because Hugo was not run.
• No cluster-facts.md was present for this item; field spelling was checked against the dossier diff and generated CRD schema hunks.

How the pages were chosen (triage report)

Feature clusters

Kept apart on purpose. Merging wrongly produces a guide that documents two things and explains neither, so these are reported for a person to merge rather than grouped automatically:

• feat(auth): add gateway Actor JWT credentials kagent#3359 and refactor(session)!: remove public suspend and resume controls kagent#3409 both have docs-site/content/kagent/1.x/observability/launch-ui.md as a candidate, but for one of them it is one page among more than 3, so they are kept apart; merge them if both drafts do land there
• feat(auth): support human and machine principals kagent#3358 and feat(auth): add gateway Actor JWT credentials kagent#3359 are a stacked pair (one depends on the other), which is a delivery detail rather than a shared feature

Draft a documentation change

kagent-dev/kagent#3359 — feat(auth): add gateway Actor JWT credentials

• Product: kagent (upstream) → kagent-dev/website
• Docs version: 1.x
• Summary (read from the body): Downstream services need to identify the executing Actor independently of who invoked it. This adds actorJwt to ModelConfig and RemoteMCPServer, and to EgressPolicy's existing authentication object.
• Not tested: no cluster was available, so every command in this diff is unrun
• No rule covers 4 touched file(s). The candidate pages below come from the files that DID match a rule, so they may scope this narrower than the change is. Read these before deciding the change is only about the pages listed:
  • docs/architecture/credential-injection.md
  • go/core/internal/controller/remotemcpserver/reconciler.go
  • go/core/internal/service/tool/mcp.go
  • go/core/internal/translator/egress.go

Draft branch: pr-tracker-draft-kagent-3359

[Rachael-Graham]

Folded into #672.