Autenticação
Client credentials, verificadas na borda.
Toda chamada carrega um token bearer OAuth2. Ele é verificado no gateway da API antes de qualquer serviço nosso ser alcançado, então uma credencial expirada ou sem escopo suficiente nunca toca o ledger. Obter uma são duas linhas de curl.
Obtendo um token
O endpoint de token é form-encoded, não JSON. Ele é deliberadamente não autenticado, porque é onde você troca as suas credenciais, e devolve 400 em vez de 401 quando elas não vêm.
curl -sX POST https://api-sbx.sonacore.com.br/auth/token \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials' \
-u "$CLIENT_ID:$CLIENT_SECRET"{
"access_token": "eyJraWQiOi…",
"expires_in": 3600,
"token_type": "Bearer"
}scope e o token volta carregando exatamente o que o seu cliente tem concedido. Peça escopos explicitamente e você prende o seu código à concessão de hoje, o que transforma uma mudança de concessão em uma mudança de cliente. Passar as credenciais no corpo em vez de com -u funciona igual.Usando o token
Um cabeçalho. Não existe chave de API, não existe cabeçalho de client id, e não há mais nada para enviar. Qualquer outra coisa que você veja mencionada é uma questão interna de limite de taxa, não parte do contrato.
curl -s https://api-sbx.sonacore.com.br/v1/health \
-H "Authorization: Bearer $ACCESS_TOKEN"Escopos
Escopos são por família de recurso, não por rota. Uma credencial de avaliação carrega estes:
| Escopo | Concede |
|---|---|
| quadra/accounts.read | Ler partes, contas, saldos e extratos |
| quadra/accounts.write | Criar partes e contas, vincular meios de pagamento |
| quadra/health | Sondas de saúde e de versão |
| quadra/holds | Colocar, capturar e liberar holds |
| quadra/obligations.write | Criar e resolver obrigações |
| quadra/products | Criar, dirigir e ler instâncias dos seus produtos |
| quadra/products.draft | Vincular um produto seu em rascunho no ambiente de avaliação |
| quadra/squads | Leituras e escritas de contas em grupo |
A taxonomia completa é maior. Uma credencial de avaliação nunca recebe quadra/operator, quadra/audit.read, quadra/gl, quadra/webhooks.admin ou quadra/scheduler.tick, então as rotas de operação, o diário de auditoria, o plano de contas e o registro de webhooks não são alcançáveis com uma. Isso é um conjunto fixo, não uma decisão por avaliador.
Um recurso que você não pode ver responde 404
Isto é normativo e vai te surpreender pelo menos uma vez. Quando você referencia um recurso que existe mas não pertence a você, a resposta é 404, não 403. Um 403 confirmaria que o recurso existe, o que transforma qualquer chute com cara de id em um oráculo de enumeração.
| Você recebe | Significa | Não |
|---|---|---|
| 401 | autenticação | O token está ausente, malformado, expirado, ou o cliente dele não está registrado no gateway. |
| 403 | escopo | O seu token é válido e falta nele um escopo que esta rota exige. O corpo é INSUFFICIENT_SCOPE. |
| 404 | propriedade | Ou o recurso não existe, ou existe e não é seu. Esses dois casos são deliberadamente indistinguíveis. |
{
"error": "INSUFFICIENT_SCOPE",
"message": "missing required scope(s): quadra/obligations.write"
}401 puro em cada chamada, o que parece credencial errada e não é. Se a sua primeira chamada der 401 com um token que você acabou de emitir com sucesso, fale com a gente em vez de rotacionar o seu secret.Obtendo credenciais
O acesso é liberado por pedido neste estágio: você pede, nós decidimos, e podemos retomar uma credencial ociosa. Isso é uma decisão de capacidade sobre um único ambiente de avaliação compartilhado, e não uma barreira comercial, e é por isso que não existe cadastro self-service. Pedir acesso.