[Design Proposal] OAuth Support 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 already includes Thunder as the identity provider and the API Platform Gateway for policy enforcement, 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, published to the Developer Portal
• 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 which acts as the OAuth key manager and token issuer.
• JWT validation policies configured in the gateway.

Currently, Agent APIs do not automatically integrate with these components.

Current workaround

Users must manually configure authentication outside the platform or expose APIs without built-in OAuth protection. This leads to inconsistent security practices and makes it harder to securely expose Agent APIs.

---

Proposed Solution

Overview

We need to:

1. Secure Agent API endpoints using OAuth/API Key authentication
2. Provide controlled consumer access via the API Platform Developer Portal:
   • Creating API Keys
   • Creating OAuth applications and generating credentials
   • Authorizing OAuth applications to Agent APIs

Key principles:

• All Agent APIs are routed through the API Platform Gateway, where access tokens are validated
• Testing is enabled via API Key authentication
• Production consumption is enabled via OAuth through the API Platform Developer Portal

---

Design

Gateway Integration

All Agent APIs are routed through the API Platform Gateway. Authentication is enforced at the gateway layer via policies.

---

Authentication Modes

1. API Key

• API Keys generated by the API Platform Gateway Controller
• Enforced using the api-key-auth policy at the gateway
• Intended for also console testing and developer portal try-out

2. OAuth (Secure Consumption)

• Enabled per Agent
• Uses client_credentials grant initially. Support for other grant types will be later.
• OAuth applications and tokens generated by the Thunder instance
• Validated via JWT-auth policy at the gateway

---

Authorization

How do we control which applications can access which Agents?

A Thunder-based authorization approach is adopted:

• Agents are represented as Resources in Thunder
• Applications authorize against specific Agent resources

Token behavior:

• JWT tokens include aud (audience) claims corresponding to the Agent resources the application is authorized to access
• Audience claims are validated by the Gateway

Requirements from Thunder:

• Resource authorization support
• Multi-audience token generation

This authorization flow will be surfaced to consumers through the API Platform Developer Portal.

---

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	Control plane synchronization of APIs created via traits is not available at the moment. Results in a hybrid model — gateways provisioned by CRs but API Key generation and retrieval controlled by a separate control plane, requiring additional implementation.
Control Plane Driven	Pushed via Controller REST API	Requires implementation of a control plane and gateway provisioning outside of OpenChoreo abstractions.

---

Developer Portal

Agent API discovery and consumption will be handled by the API Platform Developer Portal. This avoids duplicating portal infrastructure and abstracts the complexity of application management, credential generation, and authorization.

Requirements from the Developer Portal:

• Discover and browse agent APIs published from the Agent Manager Console
• View API details and specifications
• Try out Agent APIs
• Create API Keys, Delete API-Keys
• Create consumer applications
• Generate OAuth credentials (client_id, client_secret) using built-in Thunder
• Authorize applications to one or more Agent APIs
• Invoke Agent APIs securely using generated tokens

Integration is dependent on Developer Portal availability.

---

Agent Publishing

• Agents will have a Publish action in the console
• Published Agents become visible in the Developer Portal as available APIs

---

UI Support

Agent Deployment Configuration

Users can enable OAuth when configuring an Agent deployment.

Endpoint Authentication

• Security Scheme: OAuth2
• Security Header: Authorization

Agent Testing (Console)

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

Features:

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

Out of Scope

The initial implementation does not include:

• Authorization Code grant flow
• Multiple identity providers
• Advanced authorization (scopes or RBAC)

The first version focuses only on machine-to-machine API access using client_credentials.

---

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
3	Introduce api-configuration trait with JWT policy support	Done
4	Implement Test-Key feature	TBD
4.1	Implement api-key policy for Agents	TBD
4.2	Implement test-key generation endpoints	TBD
4.3	Update Swagger Testing UI for test-key generation and invocation	TBD
5	Publish Agent APIs to API Platform Developer Portal	Pending Portal Availability
5.1	Agent publishing flow (overview, try-out support)	Pending Portal Availability
6.1	Migrate API Platform Gateway to latest version (required for multi-audience JWT validation)	TBD
6.2	Migrate Thunder to latest version (required for resource authorization and multi-audience token support)	TBD