Referência

Endpoints, escopos, erros de protocolo e as configurações que controlam o Servidor OAuth.

Tudo que o servidor de autorização expõe, em um lugar. Para assinaturas dos métodos do SDK veja auth.oauth; para códigos de erro da nulvless veja Códigos de erro.

Todos os caminhos são relativos ao seu emissor.

Endpoints

Método	Caminho	Auth	O que faz
`GET`	`/.well-known/openid-configuration`	público	Documento de discovery
`GET`	`/.well-known/jwks.json`	público	Chaves públicas de assinatura
`GET`	`/oauth/authorize`	público	Inicia o fluxo, redireciona para sua tela
`GET`	`/oauth/authorizations/:id`	sessão	O que uma autorização pendente pede
`POST`	`/oauth/authorizations/:id/consent`	sessão	Registra aprovar ou negar
`POST`	`/oauth/token`	cliente	Troca um código, ou renova
`GET`	`/oauth/userinfo`	bearer	Claims dos escopos concedidos
`POST`	`/oauth/register`	público	Registro dinâmico, quando habilitado

"Público" quer dizer sem chave de API. Os dois endpoints de autorização agem em nome do usuário logado, que é o que amarra o consentimento a uma pessoa.

`GET /oauth/authorize`

Parâmetro	Obrigatório	Notas
`client_id`	sim
`redirect_uri`	sim	Casamento exato com um URI registrado
`response_type`	sim	`code`
`code_challenge`	sim	Base64url do SHA-256 do verifier
`code_challenge_method`	sim	`S256`
`scope`	não	Separado por espaço; padrão `email`
`state`	não	Devolvido intacto
`nonce`	não	Ecoado no ID token
`resource`	não	A API para a qual o token se destina

Responde 403 quando o Servidor OAuth está desligado no ambiente.

`POST /oauth/token`

Parâmetro	`authorization_code`	`refresh_token`
`grant_type`	obrigatório	obrigatório
`code`	obrigatório	—
`redirect_uri`	obrigatório	—
`code_verifier`	obrigatório	—
`refresh_token`	—	obrigatório
`client_id`	obrigatório	obrigatório
`client_secret`	clientes confidenciais	clientes confidenciais

{
  "access_token": "…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "…",
  "id_token": "…"
}

id_token só está presente quando openid foi concedido.

Escopos

Escopo	Claims
`openid`	Emite um ID token
`email`	`email`, `email_verified`
`profile`	`name`, `picture`
`phone`	`phone_number`, `phone_number_verified`

Erros de protocolo

Estas são strings de erro do OAuth 2.1, distintas dos códigos de erro da nulvless. Onde aparecem depende de o redirect URI já ter sido validado — veja o fluxo.

Erro	Significado
`invalid_request`	Parâmetro ausente ou malformado
`invalid_client`	Cliente desconhecido, ou segredo errado
`invalid_grant`	Código expirado, já usado, ou `code_verifier` não bate
`unauthorized_client`	Cliente não pode usar esse grant
`unsupported_response_type`	Qualquer coisa além de `code`
`invalid_scope`	Escopo fora do conjunto suportado
`access_denied`	O usuário clicou em Negar
`server_error`	Falha do nosso lado

Os dois que valem tratamento específico são invalid_grant — normalmente código repetido ou expirado, e sempre um recomeço do fluxo — e access_denied, que é decisão do usuário e merece uma mensagem calma, não uma página de erro.

Configurações

No Console, em Servidor OAuth, por ambiente.

Habilitadobooleano, padrão desligadoOptional

Enquanto desligado, /oauth/authorize responde 403.

URL da tela de consentimentopadrão: Site URLOptional

URL base da sua tela de consentimento, para quando ela não fica no seu Site URL.

Caminho de autorizaçãopadrão /oauth/consentOptional

Caminho da sua tela de consentimento, anexado à URL acima.

Permitir clientes dinâmicosbooleano, padrão desligadoOptional

Habilita POST /oauth/register. Veja o trade-off.

O Site URL fica nas configurações de URL do projeto, não aqui — é o mesmo valor usado nos links de confirmação.

Cache

Resposta	Header
Documento de discovery	`Cache-Control: public, max-age=3600`
JWKS	`Cache-Control: public, max-age=600`
Todo o resto	`Cache-Control: no-store`

no-store nas respostas de token é exigido pela RFC 6749 §5.1 e pelo OpenID Connect Core §3.1.3.3. Os dois documentos públicos abrem exceção de propósito, porque todo cliente os busca constantemente e eles não contêm segredo.