> ## 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.
# Autenticação, chaves e escopos da API
> Autentique-se na API da Square Cloud com uma chave de API no header Authorization, escolha os escopos de cada endpoint e restrinja a chave a recursos.
Toda requisição à API da Square Cloud leva uma chave de API. Crie chaves nas [configurações de segurança da sua conta](https://squarecloud.app/pt-br/account/security): uma conta tem até 10 chaves, cada uma com um nome, e o segredo de uma chave nova aparece uma única vez. As chaves criadas ali não expiram. As chaves que a [CLI](/pt-br/cli-reference/authentication) e a extensão do VS Code recebem quando você as conecta duram 90 dias.
## Enviando a chave
Envie a chave no header `Authorization`. O prefixo `Bearer ` é opcional.
```bash theme={"system"}
curl https://api.squarecloud.app/v2/users/me \
--header "Authorization: $SQUARECLOUD_API_KEY"
```
Mantenha a chave no seu servidor, em uma variável de ambiente. Quem tiver a chave pode agir na sua conta dentro dos escopos dela. O uso da API está sujeito aos [Termos de Serviço](https://squarecloud.app/legal) e à [Política de Uso Aceitável](https://squarecloud.app/legal/policy).
Prefere um cliente tipado? Os [SDKs da Square Cloud](/pt-br/sdks/introduction) para [JavaScript](/pt-br/sdks/js/client), [Python](/pt-br/sdks/py/client) e [Go](/pt-br/sdks/go/client) enviam a chave por você e cobrem todos os endpoints desta referência.
## Escopos
Cada chave tem escopos, que definem o que ela pode fazer. Uma chave com acesso total cobre todos os escopos, inclusive os que forem adicionados depois. Uma chamada a um endpoint fora dos escopos da chave responde `403 MISSING_SCOPE`. Não é possível editar os escopos de uma chave existente: crie uma chave nova com os escopos de que você precisa.
| Escopo | Endpoints |
| - | - |
| `account:read` | [Informações da conta](/pt-br/api-reference/endpoint/users/me) |
| `apps:read` | [Informações da aplicação](/pt-br/api-reference/endpoint/apps/info), [Status](/pt-br/api-reference/endpoint/apps/status), [Status de todas as aplicações](/pt-br/api-reference/endpoint/apps/status-all), [Logs](/pt-br/api-reference/endpoint/apps/logs), [Tempo real](/pt-br/api-reference/endpoint/apps/realtime), [Métricas](/pt-br/api-reference/endpoint/apps/metrics), [histórico de deploys](/pt-br/api-reference/endpoint/apps/deploy/list) e [deploy atual](/pt-br/api-reference/endpoint/apps/deploy/info), [registros DNS](/pt-br/api-reference/endpoint/apps/network/dns), [análise de rede](/pt-br/api-reference/endpoint/apps/network/analytics), [erros](/pt-br/api-reference/endpoint/apps/network/errors), [logs](/pt-br/api-reference/endpoint/apps/network/logs) e [performance](/pt-br/api-reference/endpoint/apps/network/performance), [Listar domínios](/pt-br/api-reference/endpoint/apps/domains), [Balanceadores de carga](/pt-br/api-reference/endpoint/apps/network/load-balancers) |
| `apps:control` | [Iniciar](/pt-br/api-reference/endpoint/apps/start), [Reiniciar](/pt-br/api-reference/endpoint/apps/restart), [Parar](/pt-br/api-reference/endpoint/apps/stop) |
| `apps:write` | [Enviar aplicação](/pt-br/api-reference/endpoint/apps/upload), [Excluir aplicação](/pt-br/api-reference/endpoint/apps/delete), [Domínio personalizado](/pt-br/api-reference/endpoint/apps/network/custom), [Limpar cache](/pt-br/api-reference/endpoint/apps/network/purge_cache) |
| `apps:deploy` | [Commit](/pt-br/api-reference/endpoint/apps/commit), [webhook do GitHub](/pt-br/api-reference/endpoint/apps/deploy/webhooks), [vincular](/pt-br/api-reference/endpoint/apps/deploy/github-app-link) e [desvincular](/pt-br/api-reference/endpoint/apps/deploy/github-app-unlink) o GitHub App |
| `files:read` | [Listar arquivos](/pt-br/api-reference/endpoint/apps/filemanager/list), [Ler arquivo](/pt-br/api-reference/endpoint/apps/filemanager/content) |
| `files:write` | [Criar ou atualizar arquivo](/pt-br/api-reference/endpoint/apps/filemanager/put), [Mover arquivo](/pt-br/api-reference/endpoint/apps/filemanager/patch), [Excluir arquivo](/pt-br/api-reference/endpoint/apps/filemanager/delete) |
| `envs:read` | [Listar variáveis de ambiente](/pt-br/api-reference/endpoint/apps/envs/get) |
| `envs:write` | [Adicionar ou editar](/pt-br/api-reference/endpoint/apps/envs/add_n_edit), [substituir](/pt-br/api-reference/endpoint/apps/envs/overwrite) e [remover](/pt-br/api-reference/endpoint/apps/envs/remove) variáveis de ambiente |
| `snapshots:read` | Listar snapshots de uma [aplicação](/pt-br/api-reference/endpoint/apps/snapshots/list), de um [banco de dados](/pt-br/api-reference/endpoint/databases/snapshots/list) ou da [conta](/pt-br/api-reference/endpoint/users/snapshots) |
| `snapshots:write` | Criar e restaurar snapshots de uma [aplicação](/pt-br/api-reference/endpoint/apps/snapshots/create) ou de um [banco de dados](/pt-br/api-reference/endpoint/databases/snapshots/create) |
| `databases:read` | [Informações do banco de dados](/pt-br/api-reference/endpoint/databases/info), [Status](/pt-br/api-reference/endpoint/databases/status), [Status de todos os bancos de dados](/pt-br/api-reference/endpoint/databases/status-all), [Métricas](/pt-br/api-reference/endpoint/databases/metrics) |
| `databases:write` | [Criar](/pt-br/api-reference/endpoint/databases/create), [editar](/pt-br/api-reference/endpoint/databases/edit), [iniciar](/pt-br/api-reference/endpoint/databases/start), [parar](/pt-br/api-reference/endpoint/databases/stop) e [excluir](/pt-br/api-reference/endpoint/databases/delete) um banco de dados |
| `databases:credentials` | [Obter certificado](/pt-br/api-reference/endpoint/databases/credentials/get_certificate), [Redefinir credenciais](/pt-br/api-reference/endpoint/databases/credentials/reset) |
| `workspaces:manage` | Todos os endpoints de [workspace](/pt-br/api-reference/endpoint/workspace/list), inclusive membros e aplicações compartilhadas |
| `ai:chat` | [AI Gateway](/pt-br/api-reference/ai-gateway) |
| `blob:read`, `blob:write` | [Blob Storage](/pt-br/blob-reference/authentication#escopos) |
A página de cada endpoint também informa o escopo dele, logo abaixo do campo `Authorization`.
Alguns escopos vão além do que o nome sugere. `files:write` e `apps:deploy` executam código de sua escolha na aplicação, `snapshots:read` baixa a aplicação inteira com as variáveis de ambiente, `envs:read` expõe todos os segredos da aplicação, `databases:credentials` entrega a senha do banco de dados, e o acesso concedido com `workspaces:manage` continua valendo depois que a chave é revogada. Dê a cada integração apenas os escopos de que ela precisa.
## Restringindo uma chave a recursos
Uma chave também pode ser limitada a até 30 aplicações e bancos de dados. Uma chamada sobre qualquer outro recurso, ou a um endpoint da conta inteira que não pode ser restrito a esses recursos, responde `403 RESOURCE_NOT_ALLOWED`. Endpoints de listagem como [Informações da conta](/pt-br/api-reference/endpoint/users/me) retornam só os recursos que a chave cobre.
Uma chave restrita não pode ter os escopos `blob:read` ou `blob:write`, porque os arquivos armazenados pertencem à conta e não a uma aplicação. Crie uma chave para as suas aplicações e outra para o Blob Storage.
## Erros
| Código | HTTP | Significado |
| - | - | - |
| `ACCESS_DENIED` | 401 | A chave está ausente, foi digitada errado, foi revogada ou expirou, ou a conta dela não existe mais. |
| `MISSING_SCOPE` | 403 | A chave não tem o escopo deste endpoint. |
| `RESOURCE_NOT_ALLOWED` | 403 | A chave está restrita a recursos que não cobrem esta requisição. |
| `RATE_LIMITED` | 429 | O limite de requisições da conta ou da chave foi atingido. |
Todos os outros códigos estão em [Erros](/pt-br/api-reference/errors).
## Proteção contra chaves inválidas
Para proteger todas as contas, a API bloqueia temporariamente um endereço IP que insiste em chaves de API que não pertencem a nenhuma conta, respondendo `429 RATE_LIMITED` por um curto período. Chaves válidas em uso normal não são afetadas. Se uma requisição receber `401`, não repita em loop: corrija ou troque a chave.
## Próximos passos
URL base, uma primeira chamada com curl e o formato das respostas.
Limites de requisições por plano e regiões bloqueadas.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.