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

# Authorization Failed - JWT Verification

If you see "Authorization Failed" in your AgentOS, the entries below cover the most common causes.

<img src="https://mintcdn.com/agno-v2-agui/B_u8TpSpMOBFKmtg/images/auth-failed.png?fit=max&auto=format&n=B_u8TpSpMOBFKmtg&q=85&s=5a4164946066f88166bdbc4ca4e5faa8" alt="Authorization Failed Error" width="507" height="355" data-path="images/auth-failed.png" />

## 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.

| Setup              | What to set                                                                                                                                 |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| AgentOS platform   | `algorithm="RS256"` or omit it (RS256 is the default). Platform-issued public keys are always RS256, so any other value fails verification. |
| Standalone AgentOS | `algorithm` must match how you signed the token.                                                                                            |

```python theme={null}
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:

```python theme={null}
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:

```bash theme={null}
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](/agent-os/security/authorization/scopes#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](/agent-os/security/authorization/scopes#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](https://docs.agno.com/agent-os/security/overview#security-key-authentication).

**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 <Badge icon="code-branch" color="orange"><Tooltip tip="Introduced in v2.3.13" cta="View release notes" href="https://github.com/agno-agi/agno/releases/tag/v2.3.13">v2.3.13</Tooltip></Badge>

<Note>
  Authorization (JWT verification) is preferred over security key authentication as it provides fine-grained RBAC permissions.
</Note>

Pick one:

<AccordionGroup>
  <Accordion title="Option 1: Switch off Authorization">
    1. **Disable Authorization** from the AgentOS Control Plane
    2. Continue using security key authentication only
  </Accordion>

  <Accordion title="Option 2: Switch to Authorization (Preferred)" defaultOpen={true}>
    1. **Disable security key authentication** from the AgentOS Control Plane
    2. **Unset the security key** from your environment:

    ```bash theme={null}
    unset OS_SECURITY_KEY
    ```

    3. **Ensure Authorization is enabled** on the AgentOS Control Plane and set the verification key. [More info](/agent-os/security/authorization/overview)

    ```bash theme={null}
    export JWT_VERIFICATION_KEY="your-public-key"
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

* [AgentOS Security overview](/agent-os/security/overview)
* [Authorization](/agent-os/security/authorization/overview)
* [AuthorizationConfig reference](/reference/agent-os/authorization-config)