[Design Proposal] Inbound Security for Agent API Interfaces

[AnoshanJ]

Problem

Agent Manager exposes APIs for agent invocation, for agents deployed on the platform, but currently these endpoints are unsecured. This creates several limitations:

• Agent API interfaces cannot enforce authentication.
• Users cannot enable or disable security per Agent API.
• API consumers cannot easily obtain credentials to securely invoke Agent APIs.
• Authentication configuration must be handled externally, outside the platform.

Since the platform includes Thunder as the identity provider and the API Platform Gateway for policy enforcement, API key and OAuth support should be integrated directly into the Agent lifecycle.

---

User Stories

• As an Agent developer, I want to enable OAuth/API-Key auth for my Agent API so that consumers must authenticate before invoking agents.
• As an API consumer, I want to generate credentials and obtain tokens so that I can securely call the Agent APIs.

---

Existing Solutions

Within the platform ecosystem, API security is typically handled through:

• API Platform Gateway policies that enforce authentication at the gateway layer.
• Thunder Identity Provider/Configurable IDP which acts as the OAuth key manager and token issuer.
• JWT validation policies configured in the gateway.

Previously, Agent APIs did not automatically integrate with these components.

Current workaround

Users had to manually configure authentication outside the platform or expose APIs without built-in OAuth/API key protection. This led to inconsistent security practices and made it harder to securely expose Agent APIs.

---

Proposed Solution

Overview

We need to:

1. Secure Agent API endpoints using API Key and OAuth authentication.
2. Route both ingress and egress traffic through the unified API Platform Gateway.
3. Provide controlled consumer access via the Console
   • Creating API Keys

Key principles:

• All Agent APIs are routed through the API Platform Gateway, where authentication policies are enforced.
• Agent API artifacts are created and synchronized with the gateway.
• API keys are created through the Agent-Manager Service and propagated through the gateway websocket connection.
• Testing is enabled via API Key authentication.

---

Design

Gateway Integration

All Agent APIs are routed through the unified API Platform Gateway.

The previous split between ingress and egress gateway paths has been replaced with a single gateway setup. The unified gateway handles:

• Agent API ingress traffic
• Trace ingestion / observability ingress
• AI API egress routing

The gateway has been upgraded to API Platform Gateway 1.1.0.

Authentication is enforced at the gateway layer via policies. Agent API configuration is attached through the api-configuration trait, which now injects required gateway metadata such as the artifact UUID.

---

Authentication Modes

1. API Key

• API Keys are generated by the Agent Manager Service.
• API keys are propagated to the gateway through the websocket connection.
• Enforced using the api-key-auth policy at the gateway.
• Intended for Try-It flows, and simple API consumption.
• Agent API key credentials are managed from the Agent Credentials page.

2. OAuth (Secure Consumption)

• Planned to be enabled per Agent.
• Make JWT policy attachment configurable via the Agent deployment/API interface configuration.
• Expose user-configurable JWT policy parameters in the UI where appropriate.
• Provide documentation for configuring required system parameters.

---

API Deployment Models

Two primary models for API creation in the gateway were evaluated:

Model	Mechanism	Identified Issues
Declarative (CRs/Traits)	Defined via Kubernetes resources	Adopted for Agent API attachment. Traits are used to configure the API, and required gateway artifact metadata such as artifact UUID is injected through the trait flow.
Control Plane Driven	Pushed via Controller REST API	API key creation and gateway-side synchronization are handled through the API Platform Gateway controller and WebSocket connection instead of fully moving API provisioning outside OpenChoreo abstractions.

---

UI Support

Agent Deployment Configuration

Users can configure endpoint authentication when deploying an Agent.

Endpoint Authentication

• Security Scheme: API Key initially
• Security Header: X-API-Key
• OAuth2 support to be introduced through configurable JWT policy support

Agent Testing (Console)

The testing page allows users to generate a short-lived test API Key and invoke the API.

Features:

• Display invoke URL
• Generate test API Key
• Automatically inject the appropriate auth header

Alternatives Considered

A custom React-based Agent Catalog was initially proposed for API discovery and consumption. This has been dropped in favor of the API Platform Developer Portal, which provides equivalent functionality without the overhead of maintaining a separate portal. Requirements for what the portal must support are documented in the Developer Portal section above.

---

Milestones

Phase	Scope	Target
1	Initial implementation design	Done
2	Add API Platform Gateway as ingress gateway	Done
2.1	Unify ingress and egress through API Platform Gateway	Done
2.2	Upgrade API Platform Gateway to 1.1.0	Done
3	Introduce api-configuration trait with JWT policy support	Done
3.1	Introduce api-configuration trait with API policy support	Done
3.1	Inject gateway artifact UUID and required metadata through traits	Done
4	Implement API key security for Agents	Done
4.1	Implement api-key policy for Agents	Done
4.2	Implement API key generation and management endpoints	Done
4.3	Push API keys to gateway through websocket connection	Done
4.4	Update Swagger/Try-It UI for API key generation and invocation	Done
5	Add configurable JWT policy for OAuth	Planned
5.1	Open Source: configure JWT policy attachment and document system params	Planned

[AnoshanJ]

Inbound security — modes we offer, and the two problems to solve

Per-agent security modes:

1. No auth — offered (shipped).
2. API key — offered (shipped).
3. OAuth-only — offered (this work; configurable jwt-auth attachment).
4. OAuth + API key — kept as draft, not offered initially. Most consumers pick one scheme; supporting both on one API needs complementary executionConditions and adds little near-term value. Modeled, deprioritized.

So the scope here is mode 3, and it surfaces two problems:

• Main problem (the Milestone 5.1 deliverable): enable OAuth/JWT per agent by attaching a configurable jwt-auth policy.
• Secondary problem: the Try-It page authenticates with a short-lived API key (X-API-Key); under OAuth-only there is no api-key-auth policy on the agent's API, so the test view has no credential the gateway accepts and every test request 401s.

We can solve this problems in two separate phases. We can ship the main problem regardless of how we later solve testing — so it is Phase 1. Solving the test flow is Phase 2.

---

Phase 1 — ship OAuth, disable Try-It under OAuth-only

Land configurable jwt-auth attachment and disable the Try-It view when the agent is OAuth-only (frontend conditional). This will ship the main backend changes and frontend required to work with JWT Policy. Nothing to remove later. The only cost is a temporary in-console testing gap for OAuth-only agents — which Phase 2 removes.

Production consumers are not blocked by the disabled Try-It view, and the issuer is the consumer's choice — we just document the flows:

Bundled Thunder: create an OAuth app in the Thunder console (http://thunder.amp.localhost:8080/console), configured to their requirements.
External IdP (e.g. Okta): register its issuer/JWKS as a key manager in the gateway system parameters (policy_configurations.jwtauth_v1.keymanagers), then select it as the agent's issuers in the deployment drawer.
Phase 1 is therefore a complete production feature for any IdP; only the in-console test convenience is deferred to Phase 2.

---

Phase 2 — restore a test flow for OAuth-only agents

Relevant facts: Agent Manager already signs RS256 JWTs and serves a JWKS (/auth/external/jwks.json) that the gateway's agent-manager-service key manager already trusts (used today for trace ingestion); jwt-auth can be attached more than once and gated per-attachment with an executionCondition; auth header is a per-policy param. Header convention: x-api-key = API key, Authorization: Bearer = OAuth, x-amp-api-key = telemetry only.

These approaches combine — pick a token source, optionally add the isolation modifier:

Token source — where the test JWT comes from (pick one)

Option	Mechanism	Pros	Cons
A. Dedicated test OAuth app	Console gets a token from a bootstrapped Thunder app; its issuer is accepted by the agent's jwt-auth	Seamless UX; useful if a console OAuth app is wanted anyway	Widens production trust unless audience-scoped / isolated via F
B. User pastes own test token	UI field; sent as Authorization: Bearer	Lowest effort, no backend; trusts nothing extra	Manual, expires mid-session, poor UX
C. AMP mints short-lived test JWT	Reuse existing signer + JWKS + agent-manager-service key manager	Seamless UX; no new signing infra	Trusts AMP issuer for customer traffic unless audience-scoped / isolated via F

Isolation modifier — optional, pairs with A or C (not standalone)

Option	Mechanism	Pros	Cons
F. Gated 2nd jwt-auth attachment	Separate test issuer gated by executionCondition, alongside the production attachment	Isolates the test path — production trust boundary untouched	More policy entries; condition/ordering care

Or defer

Option	Mechanism	Pros	Cons
E. Wait for API Platform Developer Portal	Upstream provides test-token issuance	No work now	Not a standalone OSS answer; timeline risk

Likely Phase 2 picks: C + F or A + F for a seamless, isolated test path; B alone (no isolation — uses the customer's own issuer). The decision hinges on whether the OSS jwt-auth enforces aud and whether trusting the agent-manager-service issuer for customer traffic is acceptable.