Skip to main content
AgentOS uses Role-Based Access Control (RBAC) with JWT tokens to secure your API endpoints and provide fine-grained permission control. When RBAC is enabled, include a JWT token with scopes in your requests: 
curl --location 'http://localhost:7777/agents/my-agent/runs' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'message=Your query here'

​
JWT Token Structure

Your JWT tokens should include scopes and audience claims: 
{
  "sub": "user-123",
  "aud": "my-agent-os",
  "scopes": ["agents:read", "agents:my-agent:run", "sessions:write"],
  "exp": 1735689600
}

​
Required Claims

ClaimDescription
audMust match your AgentOS id
scopesArray of permission scopes

​
Common Scopes

ScopeDescription
agents:readList and view agents
agents:runRun any agent
agents:<id>:runRun a specific agent
sessions:readView session data
sessions:writeCreate/update sessions
agent_os:adminFull admin access
See RBAC Documentation for all available scopes.

​
Error Responses

StatusDescription
401 UnauthorizedMissing or invalid JWT token
401 UnauthorizedInvalid audience (wrong AgentOS ID)
403 ForbiddenInsufficient scopes

​
Developer Resources

AgentOS Security

Enable RBAC and configure authorization.

RBAC

Complete scope reference and endpoint mappings.

JWT Middleware

JWT configuration and parameter injection.

​
Security Key Authentication (Deprecated)

Security Key authentication is deprecated. Use RBAC instead.
Legacy authentication using the OS_SECURITY_KEY environment variable: 
curl --location 'http://localhost:7777/agents/my-agent/runs' \
    --header 'Authorization: Bearer your-security-key' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'message=Your query here'