Authenticating Requests to Agent Manager

How to obtain a JWT access token, authenticate API requests with Bearer headers, associate runs with users and orgs, and handle SSE streaming auth.

Agent Manager uses JWT-based authentication backed by Spring Security. All API endpoints — including streaming and SSE connections — require a valid token. This page explains how to obtain a token, include it in your requests, and understand how identity is used to partition data across tenants.

Obtaining an access token

Use the login endpoint to exchange your credentials for a signed JWT:

curl

curl -X POST http://your-host/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "your-username", "password": "your-password"}'

Store the token value — you’ll include it in every subsequent request.

The exact authentication provider (local credentials, OAuth2 SSO) depends on your deployment configuration. Contact your platform administrator if you’re unsure which login method is configured.

Authenticating API requests

Include the token as a Bearer credential in the Authorization header of every request:

Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...

example agent run

curl -X POST http://your-host/api/agents/my-agent/runs \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..." \
  -H "Content-Type: application/json" \
  -d '{"message": "Analyze Q3 sales data"}'

Associating runs with a user and organization

When submitting a run, include userId and orgId in the request body to associate the run with a specific user and organization. This is how session history, memories, and knowledge base access are scoped:

{
  "message": "Summarize this week's incidents",
  "session_id": "optional-existing-session-uuid",
  "userId": "user-uuid",
  "orgId": "org-uuid"
}

All data — sessions, memories, and knowledge — is partitioned by orgId. Never mix orgId values between unrelated tenants. Requests that attempt to access another tenant’s resources return 404 rather than 403 to prevent existence leaks.

Authenticating SSE streaming connections

Browser EventSource connections cannot send Authorization headers. Agent Manager handles this by issuing short-lived opaque SSE tokens that you pass as a query parameter.

1. Request an SSE token

   Exchange your JWT for a short-lived SSE token scoped to a specific run:

   curl -X POST http://your-host/api/v1/runs/{runId}/sse-token \
     -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..."
   

   {
     "token": "a1b2c3d4-...",
     "expiresAt": "2024-01-15T10:31:00Z"
   }
   
2. Open the SSE connection

   Pass the token as a query parameter when opening the event stream:

   GET /api/v1/runs/{runId}/events?token=a1b2c3d4-...
   

SSE tokens are single-use, expire after 60 seconds by default, and are scoped to the run they were issued for. A leaked token is near-useless given the short TTL and single-use constraint.

Common authentication errors

Status	Meaning	Action
401 Unauthorized	Token is missing, invalid, or expired	Re-authenticate via POST /api/auth/login to obtain a fresh token
403 Forbidden	Token is valid but your role lacks permission for the requested operation	Contact your administrator to review RBAC role assignments
404 Not Found (on a known resource)	You may be accessing a resource that belongs to a different orgId	Verify you are using the correct orgId for your tenant

Registering a new user

If your deployment uses local credential management, new accounts can be registered via:

curl -X POST http://your-host/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "new-user",
    "email": "[e-mail]",
    "password": "secure-password"
  }'

Usernames and emails must be unique across the system. After registration, log in using POST /api/auth/login to obtain your token.