AgentOS Authentication

Authenticate with AgentOS using RBAC and JWT tokens

AgentOS uses Role-Based Access Control (RBAC) with JWT tokens to secure your API endpoints and provide fine-grained permission control.

RBAC Authentication (Recommended)

When RBAC is enabled, include a JWT token with scopes in your requests:

1curl --location 'http://localhost:7777/agents/my-agent/runs' \
2    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...' \
3    --header 'Content-Type: application/x-www-form-urlencoded' \
4    --data-urlencode 'message=Your query here'

JWT Token Structure

Your JWT tokens should include scopes and audience claims:

1{
2  "sub": "user-123",
3  "aud": "my-agent-os",
4  "scopes": ["agents:read", "agents:my-agent:run", "sessions:write"],
5  "exp": 1735689600
6}

Required Claims

Claim	Description
`aud`	Must match your AgentOS `id`
`scopes`	Array of permission scopes

Common Scopes

Scope	Description
`agents:read`	List and view agents
`agents:run`	Run any agent
`agents:<id>:run`	Run a specific agent
`sessions:read`	View session data
`sessions:write`	Create/update sessions
`agent_os:admin`	Full admin access

See RBAC Documentation for all available scopes.

Error Responses

Status	Description
`401 Unauthorized`	Missing or invalid JWT token
`401 Unauthorized`	Invalid audience (wrong AgentOS ID)
`403 Forbidden`	Insufficient scopes

Developer Resources

shield

AgentOS Security

Enable RBAC and configure authorization.

lock

RBAC

Complete scope reference and endpoint mappings.

key

JWT Middleware

JWT configuration and parameter injection.

Security Key Authentication (Deprecated)

Warning

Security Key authentication is deprecated. Use RBAC instead.

Legacy authentication using the OS_SECURITY_KEY environment variable:

1curl --location 'http://localhost:7777/agents/my-agent/runs' \
2    --header 'Authorization: Bearer your-security-key' \
3    --header 'Content-Type: application/x-www-form-urlencoded' \
4    --data-urlencode 'message=Your query here'