OAuth 2.1
Deixe outras aplicações iniciar a sessão dos seus utilizadores com uma conta Bot-Hosting, como o Iniciar sessão com o Discord. Baseado em OAuth 2.1 e PKCE, por isso funciona com qualquer cliente OAuth padrão.
Use uma chave de API para controlar a sua própria conta. Use OAuth quando criar uma aplicação que atua sobre contas de outras pessoas, para que iniciem sessão e consintam em vez de colar uma chave. Assistentes de IA como o ChatGPT ligam-se através deste mesmo fluxo.
O fluxo
- 01 Crie uma aplicação Registe um nome e um URI de redirecionamento nas definições de programador. Recebe um client_id público, sem segredo.
- 02 Envie os utilizadores para autorizar Redirecione para /oauth/authorize com PKCE. O utilizador inicia sessão e aprova os âmbitos.
- 03 Troque o código Regressam com um código. Faça POST ao endpoint de token para obter um token de acesso.
- 04 Invoque a API em nome deles Envie o token como Bearer para /api/v1 e renove-o em segundo plano.
Endpoints
| Endpoints | Finalidade |
|---|---|
| GET /oauth/authorize | Ecrã de consentimento do utilizador, aberto no navegador. |
| POST /api/oauth/token | Trocar um código por um token, ou renovar 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. |
Duração dos tokens
Código de autorização 10 min De utilização única, associado ao PKCE.
Token de acesso 7 dias Bearer para chamadas a /api/v1.
Refresh token 30 dias Substituído a cada utilização.
Renovação
Cada renovação devolve um novo refresh token e revoga o antigo: substitua sempre o guardado. Se uma renovação devolver invalid_grant, envie o utilizador de volta ao passo 1.
Segurança
- Guarde os tokens no servidor, associados ao seu utilizador. Nunca os envie para o navegador nem para um repositório público.
- Os tokens são revogados assim que o utilizador desliga a sua aplicação.
- Use URIs de redirecionamento https em produção. O http é aceite para testes locais.
- Os tokens OAuth nunca concedem administração, sejam quais forem os âmbitos aprovados.