# 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"
```

✓ Checkpoint: a resposta traz `access_token`, `token_type: "Bearer"`, `expires_in` (900 segundos por omissão), `refresh_token`, `active_context`, `contexts` e um `id_token` assinado.

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

- [Contextos: uma credencial, um contexto](/docs/getting-started/contexts)
- [Criar e rodar chaves de API](/docs/getting-started/api-keys)
- [Construir uma app para moradores com PKCE](/docs/guides/resident-app)

