PT EN

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#

bash
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.

json
{
  "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.

  1. Gere um code_verifier aleatório e o respectivo code_challenge em SHA-256.
  2. Envie a pessoa para /oauth/authorize com response_type=code, client_id, redirect_uri, state, code_challenge e code_challenge_method=S256. Sem code_challenge ou com outro método, o redireccionamento volta com error=invalid_request.
  3. Troque o código recebido por tokens:
bash
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.

Próximos passos#