OAuth 2.1
Deixe outros apps autenticarem seus usuários com uma conta do Bot-Hosting, como o Entrar com o Discord. Baseado em OAuth 2.1 e PKCE, funciona com qualquer cliente OAuth padrão.
Use uma chave de API para controlar a sua própria conta. Use o OAuth quando criar um app que age em contas de outras pessoas, para que elas façam login e deem consentimento em vez de colar uma chave. Assistentes de IA como o ChatGPT se conectam exatamente por esse fluxo.
O fluxo
- 01 Crie um app Registre um nome e uma URI de redirecionamento nas configurações de desenvolvedor. Você recebe um client_id público, sem segredo.
- 02 Envie os usuários para autorizar Redirecione para /oauth/authorize com PKCE. A pessoa faz login e aprova os escopos.
- 03 Troque o código por um token Ela volta com um code. Envie-o por POST ao endpoint de token para obter um token de acesso.
- 04 Chame a API em nome dela Envie o token como Bearer para /api/v1 e renove-o em segundo plano.
Endpoints
| Endpoints | Finalidade |
|---|---|
| GET /oauth/authorize | Tela de consentimento do usuário, aberta no navegador. |
| POST /api/oauth/token | Troca um code por um token, ou renova um. |
| POST /api/oauth/register | Dynamic Client Registration (RFC 7591), opcional. |
| GET /.well-known/oauth-authorization-server | Metadados de descoberta. |
| GET /.well-known/oauth-protected-resource | Metadados do recurso, usados por clientes MCP. |
Validade dos tokens
Código de autorização 10 min Uso único, vinculado ao PKCE.
Token de acesso 7 dias Bearer para chamadas a /api/v1.
Refresh token 30 dias Rotacionado a cada uso.
Renovação
Cada renovação retorna um novo refresh token e revoga o antigo: sempre sobrescreva o armazenado. Se uma renovação retornar invalid_grant, leve a pessoa de volta ao passo 1.
Segurança
- Guarde os tokens no servidor, associados ao usuário. Nunca os envie ao navegador nem a um repositório público.
- Os tokens são revogados assim que a pessoa desconecta seu app.
- Use URIs de redirecionamento https em produção. O http é aceito para testes locais.
- Tokens OAuth nunca concedem acesso de administrador, sejam quais forem os escopos aprovados.