OpenAPI Tools Authentication
Learn how to authenticate OpenAPI services with CUGA Agent using API keys, bearer tokens, and custom headers
This guide assumes you have CUGA Agent already installed. If you haven't installed CUGA yet, please follow the installation guide first.
This guide demonstrates how to set up authentication for OpenAPI services in CUGA Agent. You can either use your existing secure API or follow along with the minimal FastAPI server example we'll build together.
CUGA supports multiple authentication methods including API keys, bearer tokens, basic auth, and custom headers.
What You'll Build
This guide provides a complete authentication example. You can:
- Use your existing API - Skip to the Configure CUGA Authentication section and adapt the authentication settings for your API
- Follow the example - Build a minimal FastAPI server with API key authentication step-by-step
The example includes:
- FastAPI server with API key authentication
- CUGA configuration for secure API access
- Automatic header injection for protected endpoints
- Testing with both CUGA and curl
Prerequisites
Before starting, ensure you have:
- CUGA Agent installed - This guide assumes CUGA is already installed. If not, follow the Installation Guide first.
- Python 3.10+ - Download here
- uv package manager - Installation guide
Quick Start
Create the FastAPI Server
Create a new directory for your project and add a server.py file:
from fastapi import FastAPI, HTTPException, Security, Header
from fastapi.responses import JSONResponse
import uvicorn
from typing import Optional, Annotated
app = FastAPI(
title="Minimal Auth Example API",
description="Simple API with API Key in Header",
version="1.0.0"
)
# Mock API Key (for demonstration only)
VALID_API_KEY = "my-secret-key"
def verify_api_key(x_api_key: Annotated[Optional[str], Header()] = None) -> str:
if not x_api_key or x_api_key != VALID_API_KEY:
raise HTTPException(status_code=401, detail="Invalid X-API-Key")
return x_api_key
@app.get("/data", tags=["Protected"], operation_id="getProtectedData")
async def get_protected_data(api_key: Annotated[str, Security(verify_api_key)]):
"""
Get protected data. Requires X-API-Key header.
Requires: X-API-Key: my-secret-key
"""
return {"message": "This is protected data!", "access_granted": True}
@app.get("/health", tags=["System"])
async def health_check():
return {"status": "healthy"}
@app.exception_handler(HTTPException)
async def http_exception_handler(request, exc):
return JSONResponse(
status_code=exc.status_code,
content={
"error": exc.detail,
"status_code": exc.status_code,
}
)
if __name__ == "__main__":
print("\nMinimal Auth Example API Server running on http://localhost:8000")
print(f"Required X-API-Key: {VALID_API_KEY}\n")
uvicorn.run(app, host="0.0.0.0", port=8000, log_level="info")Security Note: Never hardcode API keys in production! Use environment variables or secure vault services instead.
Setup Dependencies
Create a pyproject.toml file to manage Python dependencies:
[project]
name = "minimal-auth-example"
version = "1.0.0"
description = "Minimal FastAPI server for CUGA Agent auth example"
requires-python = ">=3.10"
dependencies = [
"fastapi",
"uvicorn",
"pydantic",
]
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"Configure CUGA Authentication
Create or edit the mcp_servers.yaml configuration file. The default location is:
src/cuga/backend/tools_env/registry/config/mcp_servers.yamlTo use a custom file location, set the MCP_SERVERS_FILE environment variable:
export MCP_SERVERS_FILE="<path-to-your-custom-file>"Add your API configuration:
services:
- minimal-auth-api:
type: openapi
url: http://localhost:8000/openapi.json
description: "Minimal API with API Key authentication"
auth:
type: header
key: X-API-Key
value: my-secret-keyInstall and Run
Install dependencies and start your server:
# Install project dependencies
uv sync# Start the FastAPI server
uv run python server.pyThe server will be available at http://localhost:8000
# In a separate terminal, start CUGA in demo mode
cuga start demoCUGA will automatically inject the X-API-Key header when calling getProtectedData
Authentication Types
CUGA supports multiple authentication methods for OpenAPI services:
Complete Project Structure
Your project should look like this:
minimal-auth-example/
├── server.py # FastAPI server with authentication
├── pyproject.toml # Python dependencies
└── mcp_servers.yaml # CUGA configurationReal-World Examples
Example 1: GitHub API with Bearer Token
services:
- github-api:
type: openapi
url: https://api.github.com/openapi.json
description: "GitHub REST API"
auth:
type: bearer
value: ghp_your_github_token_hereExample 2: Multiple APIs with Different Auth
services:
- api-one:
type: openapi
url: https://api1.example.com/openapi.json
auth:
type: header
key: X-API-Key
value: key1
- api-two:
type: openapi
url: https://api2.example.com/openapi.json
auth:
type: bearer
value: token2Security Best Practices
Production Security
Never commit secrets to version control!
Use environment variables in your mcp_servers.yaml:
services:
- secure-api:
type: openapi
url: http://localhost:8000/openapi.json
auth:
type: header
key: X-API-Key
value: ${API_KEY} # Load from environment variableThen set the environment variable:
export API_KEY="my-secret-key"Troubleshooting
Authentication working? Try integrating your own APIs next!