Skip to main content
If you see “Authorization Failed” in your AgentOS, the entries below cover the most common causes. Authorization Failed Error

​
401 Unauthorized: algorithm mismatch

You see “Authorization Failed” on every request, consistently across machines. Cause: The algorithm configured on AuthorizationConfig does not match how the token was signed. Fix: depends on your setup.
SetupWhat to set
AgentOS platformalgorithm="RS256" or omit it (RS256 is the default). Platform-issued public keys are always RS256, so any other value fails verification.
Standalone AgentOSalgorithm must match how you signed the token.
from agno.os.config import AuthorizationConfig

AuthorizationConfig(
    verification_keys=[YOUR_KEY],
    algorithm="HS256",  # match your signing algorithm
)
Supported algorithms: RS256 and ES256 (asymmetric, public key), HS256 (symmetric, shared secret).

​
401 Unauthorized: PEM key may be mangled in env var

You see “Authorization Failed” on some machines but not others, even with the same verification key. Cause: Multi-line PEM keys can lose their newlines when passed through shell environment variables. Depending on your shell, .env loader, or how the key was pasted, the -----BEGIN PUBLIC KEY----- header, body, and footer may collapse onto one line, producing an unparseable key. Fix: Save the key to a file and load it in code: 
from agno.os.config import AuthorizationConfig

with open("/path/to/public.pem") as f:
    public_key = f.read()

AuthorizationConfig(verification_keys=[public_key], algorithm="RS256")
Or place the key in a JWKS file and point AgentOS at it: 
export JWT_JWKS_FILE="/path/to/jwks.json"

​
403 Forbidden: insufficient scopes

The token is valid but AgentOS returns 403 on a specific endpoint. Cause: The token’s scopes claim does not include the scope required by the endpoint. Unlike a 401, the token itself is fine. Fix: Check the Scope Reference for which scope each endpoint needs. A few scopes act as gates in the platform and a token missing any of them fails before finer-grained checks run. See Access Prerequisites for the full list.

​
Both security key and JWT authorization enabled

You enabled both security key authentication and JWT authorization on the AgentOS Control Plane at the same time. Cause: Authorization is preferred over security key. When both are enabled, security key requests fail. Learn more about security key. Fix: depends on your AgentOS version.

​
Before v2.3.13

The platform only supports security key authentication on these versions. Disable Authorization on the AgentOS Control Plane and continue using security key.

​
v2.3.13 and later

Authorization (JWT verification) is preferred over security key authentication as it provides fine-grained RBAC permissions.
Pick one:
  1. Disable Authorization from the AgentOS Control Plane
  2. Continue using security key authentication only

Option 2: Switch to Authorization (Preferred)

  1. Disable security key authentication from the AgentOS Control Plane
  2. Unset the security key from your environment:
unset OS_SECURITY_KEY
  1. Ensure Authorization is enabled on the AgentOS Control Plane and set the verification key. More info
export JWT_VERIFICATION_KEY="your-public-key"

​
Next Steps