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

# JSON Web Tokens (JWT)

> JWT claim structure, example tokens, and how AgentOS reads them.

AgentOS reads the JWT from the `Authorization: Bearer <token>` header on every request. Tokens can come from the AgentOS control plane or your own backend.

## Token Structure

Your JWT tokens should include:

```json theme={null}
{
  "sub": "user-123",
  "scopes": ["agents:read", "agents:my-agent:run"],
  "exp": 1735689600,
  "iat": 1735603200
}
```

| Claim        | Required | Description                                                                                                  |
| ------------ | -------- | ------------------------------------------------------------------------------------------------------------ |
| `scopes`     | Yes      | Array of permission scopes                                                                                   |
| `sub`        | No       | User ID (extracted as `user_id`)                                                                             |
| `session_id` | No       | Session ID for session tracking                                                                              |
| `aud`        | No       | Audience (must match the configured `audience`, or the AgentOS `id` by default, when `verify_audience=True`) |
| `exp`        | No       | Expiry timestamp. Recommended; expired tokens are rejected.                                                  |
| `iat`        | No       | Issued-at timestamp.                                                                                         |

## Example Tokens

**Read-only access:**

```json theme={null}
{
  "scopes": ["agents:read", "teams:read", "sessions:read"]
}
```

**Run a specific agent:**

```json theme={null}
{
  "scopes": ["agents:my-agent:run", "agents:my-agent:read", "sessions:write"]
}
```

**Admin access:**

```json theme={null}
{
  "scopes": ["agent_os:admin"]
}
```

See [Scopes](/agent-os/security/authorization/scopes) for the full list.

## Sending Tokens

Send the token in the `Authorization` header:

```bash theme={null}
curl -H "Authorization: Bearer $TOKEN" http://localhost:7777/agents
```

JWTs identify human callers. For machine callers, mint a [service account](/agent-os/security/authorization/service-accounts) token instead. `agno tokens create <name>` returns an `agno_pat_...` token that you send in the same `Authorization` header.

## Next Steps

| Task                               | Guide                                                                 |
| ---------------------------------- | --------------------------------------------------------------------- |
| Issue tokens from your own backend | [Self-Hosted](/agent-os/security/authorization/self-hosted)           |
| Authenticate machine callers       | [Service Accounts](/agent-os/security/authorization/service-accounts) |
| See the full scope reference       | [Scopes](/agent-os/security/authorization/scopes)                     |
| Configure JWT middleware directly  | [JWT Middleware](/agent-os/middleware/jwt)                            |