Autenticação
Que credencial usar em cada cliente (chave de API, OAuth com PKCE ou device grant), como enviá-la e o que a API devolve quando a recusa.
Todos os pedidos autenticados enviam a credencial no cabeçalho Authorization com o esquema Bearer. O que muda é a origem da credencial: uma chave de API para servidores, um token OAuth obtido com PKCE para aplicações onde uma pessoa inicia sessão, ou um token obtido por device grant para ferramentas de linha de comandos.
| Cliente | Credencial | Onde a obtém |
|---|---|---|
| Servidor, tarefa agendada, integração | Chave de API (sk_live_, sk_rlive_, sk_test_, sk_rtest_) |
Programadores > Chaves de API no painel |
| Aplicação web ou móvel com sessão de pessoa | Token de acesso OAuth (Authorization Code com PKCE) | /oauth/authorize e /oauth/token |
| Linha de comandos ou dispositivo sem browser | Token de acesso OAuth (device grant) | /oauth/device_authorization e /oauth/token |
Uma chave de API nunca deve estar em código que corre no browser ou dentro de uma aplicação móvel: quem a extrair actua com todas as permissões dela.
Chaves de API#
curl -sS "$BUSINESS_API/customers?limit=1" \
-H "Authorization: Bearer $API_KEY"
Quando a credencial falta ou é recusada, a resposta é 401 em application/problem+json. Se enviou um token Bearer, a resposta traz também WWW-Authenticate: Bearer error="invalid_token", o que indica ao cliente que deve renovar o token em vez de pedir à pessoa que volte a entrar.
{
"type": "about:blank",
"title": "Unauthorized",
"status": 401,
"detail": "Credentials have been revoked",
"instance": "$BUSINESS_API/customers",
"code": "UNAUTHORIZED",
"error_code": "auth.unauthenticated",
"request_id": "req_9c1e4b7a2f6d48e0b3a5c8d1f7e2a940"
}
O detail distingue uma chave revogada (Credentials have been revoked), expirada (Credentials have expired) ou inexistente (Invalid or missing authentication credentials). Uma chave com Endereços permitidos também é recusada com 401 quando o pedido vem de outro endereço. O campo type aponta para a página de erros do site quando o operador configurou a origem do site; caso contrário vale about:blank.
OAuth 2.0 com PKCE#
Os clientes OAuth são públicos (sem segredo de cliente) e são registados pelo operador da instalação em security.oauth.clients, com o id e os redirect_uris permitidos. O documento de descoberta em https://api.gota.umbeluzi.com/.well-known/oauth-authorization-server lista os endpoints, code_challenge_methods_supported: ["S256"] e os âmbitos openid, offline_access, profile e email.
- Gere um
code_verifieraleatório e o respectivocode_challengeem SHA-256. - Envie a pessoa para
/oauth/authorizecomresponse_type=code,client_id,redirect_uri,state,code_challengeecode_challenge_method=S256. Semcode_challengeou com outro método, o redireccionamento volta comerror=invalid_request. - Troque o código recebido por tokens:
curl -sS -X POST "https://api.gota.umbeluzi.com/oauth/token" \
-d grant_type=authorization_code \
-d client_id=app-moradores \
-d code="$CODE" \
-d redirect_uri="$REDIRECT_URI" \
-d code_verifier="$CODE_VERIFIER"
Os endpoints /oauth/* recusam pedidos autenticados com uma chave de API.
Device grant#
Para a linha de comandos, POST /oauth/device_authorization com client_id devolve device_code, user_code, verification_uri, verification_uri_complete, expires_in e interval. A pessoa abre o endereço e confirma o código; entretanto o cliente consulta /oauth/token com grant_type=urn:ietf:params:oauth:grant-type:device_code e recebe authorization_pending, slow_down, expired_token ou access_denied até a autorização terminar.
A CLI faz isto com gotactl auth login. As opções são --web (entra pelo browser com PKCE), --with-api-key (lê uma chave de API da entrada padrão e guarda-a no porta-chaves) e --context (entra directamente num contexto pelo seu ID). gotactl auth status mostra o perfil e o emissor activos.