+++
title = "API Error 403: Forbidden"
weight = 104
updated = 2026-10-13
aliases = ["/docs/api-error-403-forbidden.html", "/docs/troubleshooting/api-errors/403-forbidden/", "/docs/api/errors/403-forbidden/"]

[extra]
nav_title = "API Error 403: Forbidden"
weight = 50
+++

{{ legacy_api_notice() }}

An HTTP 403: Forbidden error means the API understood the request, but is refusing to authorize it. This is distinct from an authentication error ([401: Unauthorized](@/docs/api/legacy/errors/401-unauthorized/index.md)), in that the authentication credentials are correct, but there is some other reason the request is not authorized.

This happens when the API token doesn't have the [scope](@/docs/account/api-tokens/index.md#scopes) the call needs. Every API call needs one scope:

| Scope | API calls |
| --- | --- |
| `account:read` | Listing and reading [plans](@/docs/api/legacy/endpoints/plans-api/index.md), [spaces](@/docs/api/legacy/endpoints/spaces-api/index.md) and [releases](@/docs/api/legacy/endpoints/releases-api/index.md) |
| `clusters:read` | Listing and reading [clusters](@/docs/api/legacy/endpoints/cluster-api/index.md) |
| `clusters:write` | Creating, updating and deleting [clusters](@/docs/api/legacy/endpoints/cluster-api/index.md) |

## Example

A call that needs a scope the token doesn't have results in a response like this one, from a token without `clusters:write` trying to create a cluster:

```json
{
  "errors": [
    "This API token does not have the clusters:write scope, which this action needs."
  ],
  "status": 403
}
```

The message names the missing scope. The `"status": 403` key indicates that the error is indeed an HTTP 403: Forbidden error.

## Troubleshooting

If the error names a missing scope, the token can't be changed to add it: [create a new token](@/docs/account/api-tokens/index.md) with that scope, switch your application to it, then revoke the old one. Your role on the account limits which scopes you can give a token; for example, only admins can give a token `clusters:write`. If the scope is disabled on the new token form, ask an admin of the account to create the token.

If the error doesn't name a scope, it says `This action is not available to API tokens.` Please [reach out to us](mailto:support@bonsai.io) with the request you made.