OAuth2 em nome de alguém

Quando a sua aplicação precisa agir como uma pessoa — saber quem ela é, listar os servidores dela —, o caminho é OAuth2, com os mesmos passos de sempre: você manda a pessoa para a tela de autorização, recebe um código e troca o código por um token.

Se tudo o que você quer é colocar um bot num servidor, você não precisa de nada disto: o scope=bot resolve sozinho, sem código e sem segredo. Veja Aplicações e bots.

Escopos

Escopo	O que dá
bot	instala o bot num servidor (não gera token de pessoa)
identify	id, nome, @ e foto. Não inclui e-mail
email	o e-mail da conta
guilds	a lista de servidores da pessoa
guilds.join	colocar a pessoa num servidor

Peça o mínimo. A tela de autorização mostra escopo por escopo, e escopo demais é o que faz alguém desistir ali.

1. Cadastrar o endereço de retorno

Em /developers, na sua aplicação, campo Redirect URIs — um por linha. O retorno precisa bater exatamente com um dos cadastrados, senão a autorização é recusada.

Gere também o client secret nessa tela. Ele fica no servidor do seu bot, nunca no navegador.

2. Mandar a pessoa autorizar

https://app.concord.win/oauth2/authorize
  ?client_id=47
  &scope=identify%20guilds
  &redirect_uri=https%3A%2F%2Fmeuapp.exemplo%2Fcallback
  &state=<valor aleatório e único>

O state não é enfeite: é ele que amarra o retorno ao pedido que você fez e evita CSRF. Guarde-o na sessão e confira quando voltar.

Autorizando, a pessoa é mandada de volta com o código:

https://meuapp.exemplo/callback?code=xxxxxxxx&state=…

PKCE

Para cliente público (app móvel, SPA), mande code_challenge no pedido e code_verifier na troca. O segredo deixa de ser necessário.

3. Trocar o código por token

application/x-www-form-urlencoded, como manda o padrão:

curl -X POST https://app.concord.win/api/oauth2/token \
  -d grant_type=authorization_code \
  -d client_id=47 \
  -d client_secret=<segredo> \
  -d code=xxxxxxxx \
  -d redirect_uri=https://meuapp.exemplo/callback

{
  "access_token": "…",
  "token_type": "Bearer",
  "expires_in": 604800,
  "refresh_token": "…",
  "scope": "guilds identify"
}

O código vale uma vez só e por 60 segundos — troque assim que ele chegar, no mesmo request do callback; não enfileire. O access_token dura 7 dias (expires_in: 604800).

As credenciais também podem ir em Authorization: Basic base64(client_id:client_secret), se o seu cliente preferir.

4. Usar

GET /api/oauth2/@me
Authorization: Bearer <access_token>

Bot e Bearer não são a mesma coisa

Authorization: Bot <token> é a aplicação agindo como ela mesma. Authorization: Bearer <token> é a aplicação agindo em nome de uma pessoa, dentro dos escopos que ela autorizou. Trocar um pelo outro dá 401.

5. Renovar

curl -X POST https://app.concord.win/api/oauth2/token \
  -d grant_type=refresh_token \
  -d client_id=47 \
  -d client_secret=<segredo> \
  -d refresh_token=<refresh>

O refresh é rotativo: o antigo morre e você recebe outro. Guarde o novo ou a próxima renovação falha.

Revogar

Quem autorizou vê tudo em Configurações → Apps autorizados, com um botão de desautorizar por aplicação. Pelo HTTP, com a sessão da própria pessoa:

DELETE /api/oauth2/authorizations/{aplicacao}

Revogar apaga as concessões daquela aplicação para aquela pessoa: os tokens param de valer na hora.

Seu código tem de estar preparado para levar 401 a qualquer momento — autorização é coisa que a pessoa tira quando quiser, e tem todo o direito.