> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Denied Requests

A request IAM refuses answers `403` with the code `10010`. The detail names the action the request needed and says whether no role allowed it or a role denied it, and a deny names the roles behind it. A route with no action is the one refusal whose detail names no action.

## No Role Allows the Action

```json Output theme={null}
{
  "errors": [
    {
      "code": "10010",
      "title": "Authorization failed",
      "detail": "no grant allows connection.update",
      ...
    }
  ]
}
```

The principal holds no role with an allow statement for the action, or holds no grant at all. Add the action to a role the principal holds, or grant one, and the request passes within five seconds.

## A Role Denies the Action

```json Output theme={null}
{
  "errors": [
    {
      "code": "10010",
      "title": "Authorization failed",
      "detail": "a granted role denies number.delete",
      "meta": {
        "denied_role_ids": [
          "3741a8a1-9ae2-4731-8c92-645883be671e"
        ],
        ...
      }
    }
  ]
}
```

`denied_role_ids` lists every granted role with a deny statement matching the action. A deny wins over any allow, so the request passes only once no granted role denies it.

## The Route Has No Action

A route that declares no [action](https://developers.telnyx.com/docs/iam/access/actions.md#routes-without-an-action) is refused for a principal IAM manages. The detail names the request and the principal instead of an action, and for a service account token it names the service account.

```json Output theme={null}
{
  "errors": [
    {
      "code": "10010",
      "title": "Authorization failed",
      "detail": "The request GET /v2/... is not permitted to user '3b52b5e6-f289-45a9-8543-3a86d0e1ae1b' by the organization.",
      ...
    }
  ]
}
```

No role can cover the route until it has an action.

## Other Refusals

| Response | Meaning |
| - | - |
| `401` | The credential is invalid, expired, revoked, or sent from an address the key does not accept. IAM never decided the request. |
| `403`, feature blocked | The organization's [account level](https://developers.telnyx.com/docs/account-setup/levels-and-capabilities.md) does not include the product. Roles cannot change that. |
| `403` on `/v2/iam/...` with no detail | The request did not come from the [organization owner](https://developers.telnyx.com/docs/iam/principals/organization-owner.md). Service account tokens cannot manage IAM. |

## What to Check

1. `GET /v2/iam/settings` shows whether IAM is enabled. With it disabled, grants decide nothing.
2. `GET /v2/iam/grants?filter[principal_type]=...&filter[principal_id]=...` lists the principal's roles.
3. `GET /v2/iam/roles/{role_id}/statements` shows each role's statements. The action must appear in an allow statement, exactly or under a wildcard, and in no deny statement.
4. `GET /v2/iam/actions?filter[path][contains]=...` confirms which action the route declares.
5. A change made in the last five seconds may not have reached the request yet.

[Explain](https://developers.telnyx.com/docs/iam/troubleshooting/explain-and-simulate.md) answers the first four questions in one request.

## Errors From the IAM Endpoints

| Code | When |
| - | - |
| `10012` Duplicate resource | A role name already used in the organization, or a role already granted to the principal. |
| `10027` Invalid role statements | A statement names an action that does not exist, or a wildcard that matches none. |
| `10027` Unprocessable Entity | A grant names a principal that does not exist in the organization, the owner, or an eleventh role for the principal. |
| `10021` Resource in use | A role deleted while a grant names it. |
| `10005` Resource not found | A role, statement, or grant ID that does not exist, including one that belongs to another organization. |
