Skip to main content
Toda requisição à API da Square Cloud leva uma chave de API. Crie chaves nas configurações de segurança da sua conta: 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 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.
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 e à Política de Uso Aceitável.
Prefere um cliente tipado? Os SDKs da Square Cloud para JavaScript, Python e Go 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. 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 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

Todos os outros códigos estão em Erros.

​
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

Sua primeira requisição

URL base, uma primeira chamada com curl e o formato das respostas.

Limites e restrições

Limites de requisições por plano e regiões bloqueadas.