> ## Documentation Index
> Fetch the complete documentation index at: https://operativusai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST http://your-host/api/auth/login \
    -H "Content-Type: application/json" \
    -d '{"username": "your-username", "password": "your-password"}'
  ```

  ```json response theme={null}
  {
    "token": "eyJhbGciOiJIUzI1NiJ9...",
    "id": "user-uuid",
    "username": "your-username",
    "email": "you@example.com",
    "roles": ["ROLE_USER"]
  }
  ```
</CodeGroup>

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

<Note>
  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.
</Note>

## Authenticating API requests

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

```bash theme={null}
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...
```

<CodeGroup>
  ```bash example agent run theme={null}
  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"}'
  ```

  ```bash example list sessions theme={null}
  curl http://your-host/api/sessions \
    -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..."
  ```
</CodeGroup>

## 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:

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

<Warning>
  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.
</Warning>

## 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.

<Steps>
  <Step title="Request an SSE token">
    Exchange your JWT for a short-lived SSE token scoped to a specific run:

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

    ```json theme={null}
    {
      "token": "a1b2c3d4-...",
      "expiresAt": "2024-01-15T10:31:00Z"
    }
    ```
  </Step>

  <Step title="Open the SSE connection">
    Pass the token as a query parameter when opening the event stream:

    ```bash theme={null}
    GET /api/v1/runs/{runId}/events?token=a1b2c3d4-...
    ```
  </Step>
</Steps>

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:

```bash theme={null}
curl -X POST http://your-host/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "new-user",
    "email": "new-user@example.com",
    "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.