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

# API authentication, keys and scopes

> Authenticate to the Square Cloud API with an API key in the Authorization header, pick the scopes each endpoint needs and limit a key to specific resources.

Every request to the Square Cloud API carries an API key. Create keys in your [account security settings](https://squarecloud.app/en/account/security): an account holds up to 10 of them, each with a name, and the secret of a new key is shown only once. Keys you create there don't expire. The keys the [CLI](/en/cli-reference/authentication) and the VS Code extension receive when you connect them last 90 days.

## Sending the key

Send the key in the `Authorization` header. The `Bearer ` prefix is optional.

```bash theme={"system"}
curl https://api.squarecloud.app/v2/users/me \
  --header "Authorization: $SQUARECLOUD_API_KEY"
```

Keep the key on your server, in an environment variable. Anyone who has it can act on your account within its scopes. The use of the API is subject to the [Terms of Service](https://squarecloud.app/legal) and the [Acceptable Use Policy](https://squarecloud.app/legal/policy).

<Tip>
  Prefer a typed client? The [Square Cloud SDKs](/en/sdks/introduction) for [JavaScript](/en/sdks/js/client), [Python](/en/sdks/py/client) and [Go](/en/sdks/go/client) send the key for you and wrap every endpoint of this reference.
</Tip>

## Scopes

Each key carries scopes, which decide what it can do. A key with full access covers every scope, including the ones added later. A call to an endpoint outside the key's scopes answers `403 MISSING_SCOPE`. Scopes can't be edited on an existing key: create a new key with the scopes you need.

| Scope | Endpoints |
| - | - |
| `account:read` | [Account Information](/en/api-reference/endpoint/users/me) |
| `apps:read` | [Application Info](/en/api-reference/endpoint/apps/info), [Status](/en/api-reference/endpoint/apps/status), [Status of all applications](/en/api-reference/endpoint/apps/status-all), [Logs](/en/api-reference/endpoint/apps/logs), [Realtime](/en/api-reference/endpoint/apps/realtime), [Metrics](/en/api-reference/endpoint/apps/metrics), [deploy history](/en/api-reference/endpoint/apps/deploy/list) and [current deploy](/en/api-reference/endpoint/apps/deploy/info), [DNS records](/en/api-reference/endpoint/apps/network/dns), [network analytics](/en/api-reference/endpoint/apps/network/analytics), [errors](/en/api-reference/endpoint/apps/network/errors), [logs](/en/api-reference/endpoint/apps/network/logs) and [performance](/en/api-reference/endpoint/apps/network/performance), [List Domains](/en/api-reference/endpoint/apps/domains), [Load Balancers](/en/api-reference/endpoint/apps/network/load-balancers) |
| `apps:control` | [Start](/en/api-reference/endpoint/apps/start), [Restart](/en/api-reference/endpoint/apps/restart), [Stop](/en/api-reference/endpoint/apps/stop) |
| `apps:write` | [Upload Application](/en/api-reference/endpoint/apps/upload), [Delete Application](/en/api-reference/endpoint/apps/delete), [Custom Domain](/en/api-reference/endpoint/apps/network/custom), [Purge Cache](/en/api-reference/endpoint/apps/network/purge_cache) |
| `apps:deploy` | [Commit](/en/api-reference/endpoint/apps/commit), [GitHub webhook](/en/api-reference/endpoint/apps/deploy/webhooks), [link](/en/api-reference/endpoint/apps/deploy/github-app-link) and [unlink](/en/api-reference/endpoint/apps/deploy/github-app-unlink) the GitHub App |
| `files:read` | [List Files](/en/api-reference/endpoint/apps/filemanager/list), [Read File](/en/api-reference/endpoint/apps/filemanager/content) |
| `files:write` | [Write File](/en/api-reference/endpoint/apps/filemanager/put), [Move File](/en/api-reference/endpoint/apps/filemanager/patch), [Delete File](/en/api-reference/endpoint/apps/filemanager/delete) |
| `envs:read` | [Get Environment Variables](/en/api-reference/endpoint/apps/envs/get) |
| `envs:write` | [Add or edit](/en/api-reference/endpoint/apps/envs/add_n_edit), [replace](/en/api-reference/endpoint/apps/envs/overwrite) and [remove](/en/api-reference/endpoint/apps/envs/remove) environment variables |
| `snapshots:read` | List snapshots of an [application](/en/api-reference/endpoint/apps/snapshots/list), a [database](/en/api-reference/endpoint/databases/snapshots/list) or the [account](/en/api-reference/endpoint/users/snapshots) |
| `snapshots:write` | Create and restore snapshots of an [application](/en/api-reference/endpoint/apps/snapshots/create) or a [database](/en/api-reference/endpoint/databases/snapshots/create) |
| `databases:read` | [Database Info](/en/api-reference/endpoint/databases/info), [Status](/en/api-reference/endpoint/databases/status), [Status of all databases](/en/api-reference/endpoint/databases/status-all), [Metrics](/en/api-reference/endpoint/databases/metrics) |
| `databases:write` | [Create](/en/api-reference/endpoint/databases/create), [Edit](/en/api-reference/endpoint/databases/edit), [Start](/en/api-reference/endpoint/databases/start), [Stop](/en/api-reference/endpoint/databases/stop) and [Delete](/en/api-reference/endpoint/databases/delete) a database |
| `databases:credentials` | [Get Certificate](/en/api-reference/endpoint/databases/credentials/get_certificate), [Reset Credentials](/en/api-reference/endpoint/databases/credentials/reset) |
| `workspaces:manage` | Every [workspace](/en/api-reference/endpoint/workspace/list) endpoint, including members and shared applications |
| `ai:chat` | [AI Gateway](/en/api-reference/ai-gateway) |
| `blob:read`, `blob:write` | [Blob Storage](/en/blob-reference/authentication#scopes) |

Each endpoint page also names its scope, right below the `Authorization` field.

<Warning>
  Some scopes reach further than their name suggests. `files:write` and `apps:deploy` run code of your choice in the application, `snapshots:read` downloads the whole application with its environment variables, `envs:read` exposes every secret of the application, `databases:credentials` gives the database password, and access granted with `workspaces:manage` keeps working after the key is revoked. Give each integration only the scopes it needs.
</Warning>

## Restricting a key to resources

A key can also be limited to up to 30 applications and databases. A call about any other resource, or to an account-wide endpoint that can't be narrowed to those resources, answers `403 RESOURCE_NOT_ALLOWED`. Listing endpoints such as [Account Information](/en/api-reference/endpoint/users/me) return only the resources the key covers.

A restricted key can't carry the `blob:read` or `blob:write` scopes, because stored files belong to the account and not to an application. Create one key for your applications and another one for Blob Storage.

## Errors

| Code | HTTP | Meaning |
| - | - | - |
| `ACCESS_DENIED` | 401 | The key is missing, mistyped, revoked or expired, or its account no longer exists. |
| `MISSING_SCOPE` | 403 | The key lacks the scope of this endpoint. |
| `RESOURCE_NOT_ALLOWED` | 403 | The key is restricted to resources that don't cover this request. |
| `RATE_LIMITED` | 429 | The request budget of the account or key was reached. |

Every other code is in [Errors](/en/api-reference/errors).

## Protection against invalid keys

To protect every account, the API temporarily blocks an IP address that insists on API keys that don't belong to any account, answering `429 RATE_LIMITED` for a short period. Valid keys in normal use are not affected. If a request gets a `401`, don't retry it in a loop: fix or replace the key.

## Next steps

<CardGroup cols={2}>
  <Card title="Your first request" icon="book-open" href="/en/api-reference/introduction">
    Base URL, a first curl call and the response format.
  </Card>

  <Card title="Limits and restrictions" icon="shield" href="/en/api-reference/limitations-and-restrictions">
    Request budgets per plan and blocked regions.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.