Security & Auth

Authentication modes, service account tokens, and the single auth layer covering every AgentOS surface.

AgentOS installs one auth layer that covers the REST API, the MCP server at /mcp, interfaces (A2A, AG-UI), and WebSockets. The layer runs in one of three authentication modes:

Mode	Active when	Behavior
jwt	authorization=True, JWT env vars (JWT_VERIFICATION_KEY / JWT_JWKS_FILE), or a manually installed JWTMiddleware	JWTs prove identity and scopes control permissions per endpoint. Recommended for production.
security_key	OS_SECURITY_KEY is set and no JWT source is configured	A shared key proves identity. No per-endpoint permissions.
none	Neither is configured	All requests pass. Development only.

JWT configuration takes precedence over the security key. Service account tokens authenticate in all three modes.

Authorization (JWT)

AgentOS validates JWT tokens and checks scopes against required permissions for each endpoint. Enable it with authorization=True:

from agno.os import AgentOS

agent_os = AgentOS(
    id="my-agent-os",
    agents=[my_agent],
    authorization=True,
)

Tokens can be issued by the AgentOS control plane, your own backend, or a third-party identity provider like WorkOS, Auth0, or Okta. Requests without a valid JWT return 401 Unauthorized; requests with insufficient scopes return 403 Forbidden.

See Authorization for the full setup.

Service Accounts (Machine Tokens)

Machine callers such as coding agents, chat apps, and CI pipelines authenticate with opaque agno_pat_... tokens instead of JWTs. Tokens are minted through the API or agno tokens create, carry their own scopes, and attribute every run to an sa:<name> principal:

curl -X POST http://localhost:7777/agents/my-agent/runs \
  -H "Authorization: Bearer agno_pat_..." \
  -d "message=hello" -d "stream=false"

Service account scopes are ACL data stored in your database, so they are enforced in every authentication mode, including security_key and none.

See Service Accounts for minting, scoping, and revocation.

Security Key

Set a shared secret in the OS_SECURITY_KEY environment variable:

export OS_SECURITY_KEY="your-secret-key"

Requests without a valid Authorization: Bearer <key> header return 401 Unauthorized. This is the simplest path to a protected AgentOS, suitable for local development or single-team prototypes. A valid key is a trusted root: it passes every endpoint and can mint service account tokens.

For production deployments, use Authorization instead.

Next Steps

Authorization

JWT validation, scopes, roles, and per-user data isolation.

Service Accounts

Mint, scope, and revoke opaque machine tokens.

JWT Middleware

Token sources, claim extraction, and parameter injection.

Scopes

The full permission reference for every AgentOS endpoint.