# Authorization Failed - JWT Verification (/faq/rbac-auth-failed)



The entries below cover the most common causes of "Authorization Failed" in AgentOS.

<ImageZoom src="/images/auth-failed.png" alt="Authorization Failed Error" width="507" height="355" />

Authenticating with `agno_pat_` service-account tokens instead of JWTs? See [Service Accounts](/agent-os/security/authorization/service-accounts) for their failure modes.

## 401 Unauthorized: algorithm mismatch [#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 Control Plane | `algorithm="RS256"` or omit it (RS256 is the default). Control Plane-issued public keys are always RS256, so any other value fails verification. |
| Standalone AgentOS    | `algorithm` must match how you signed the token.                                                                                                 |

```python
from agno.os.config import AuthorizationConfig

AuthorizationConfig(
    verification_keys=[YOUR_KEY],
    algorithm="HS256",  # match your signing algorithm
)
```

Supported algorithms: `RS256`, `RS384`, `RS512`, `HS256`, `HS384`, `HS512`, `ES256`, `ES384`, and `ES512`.

## 401 Unauthorized: PEM key may be mangled in env var [#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
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
export JWT_JWKS_FILE="/path/to/jwks.json"
```

## 403 Forbidden: insufficient scopes [#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 AgentOS backend, 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 [#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 takes precedence over security key authentication, so when both are enabled, security key requests fail. See [security key authentication](/agent-os/security/overview#security-key).

**Fix:** depends on your AgentOS version.

### Before v2.3.13 [#before-v2313]

The AgentOS Control Plane 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 (v2.3.13) [#v2313-and-later-v2313]

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

Pick one:

<AccordionGroup defaultValue="[&#x22;Option 2: Switch to Authorization (Preferred)&#x22;]">
  <Accordion title="Option 1: Switch off Authorization">
    1. Configure the server with `authorization=False` and remove any JWT verification configuration. Unset both `JWT_VERIFICATION_KEY` and `JWT_JWKS_FILE`; either variable can enable JWT verification even when `authorization=False`.
    2. Set `OS_SECURITY_KEY` on the server and restart it so the new authentication mode takes effect.
    3. Update the Control Plane connection to use that security key. Changing only the UI setting does not change the server's authentication mode.
  </Accordion>

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

    ```bash
    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
    export JWT_VERIFICATION_KEY="your-public-key"
    ```
  </Accordion>
</AccordionGroup>

## Next Steps [#next-steps]

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