Autenticação
Bearer token, escopos mínimos, allowlist de IP e o que acontece quando a chave é revogada.
Toda chamada autenticada leva o token no header Authorization: Bearer gos_… (ou X-API-Key, equivalente). Sem token válido: 401 unauthorized.
Escopos
Cada rota exige um ou mais escopos explícitos, marcados na criação da chave. Falta algum? A resposta é 403 forbidden_scope e a mensagem nomeia exatamente o que falta — nunca um 404 disfarçado.
Allowlist de IP (opcional)
Uma chave pode ser restrita a uma lista de IPs exatos (sem CIDR). Vazio = sem restrição, o comportamento padrão. Fora da lista: 403 forbidden_ip.
Expiração, rotação e revogação
Chave nova expira em 1 ano por padrão (dá pra escolher 90 dias ou nunca). Rotacionar troca o token mantendo uma janela de 24h em que o antigo ainda funciona — pra trocar no seu sistema sem downtime. Revogar corta o acesso em até 60 segundos (o tempo que uma chave revogada ainda pode estar em cache do lado do servidor).