OAuth2

OAuth2 é como um usuário concede acesso a um aplicativo à sua conta. O mesmo passo de consentimento pode instalar o bot do aplicativo em um servidor ou mensagem direta em grupo. Registros de aplicação, segredos de cliente e credenciais de bot pertencem ao recurso de Aplicações.

Concessão de código de autorização

A concessão começa em Autorizar aplicação. Essa rota redireciona o navegador para a interface de consentimento do Decoding Chat, a menos que a requisição defina prompt=none. Conceder consentimento OAuth2 registra a decisão, emite um código de autorização e retorna a URL de callback que o contém. O cliente apresenta esse código a Trocar token OAuth2 com suas credenciais de cliente e recebe um par de tokens de acesso e atualização.

Proof Key for Code Exchange (PKCE) suporta os métodos de desafio S256 e plain, e o Decoding Chat vincula o desafio ao código quando o emite. Um code_challenge fornecido sem code_challenge_method é tratado como plain. Uma troca por um código que tem desafio fornece um code_verifier correspondente, e uma troca por um código que não tem ignora qualquer verificador fornecido.

Credenciais e validades

Trate códigos de autorização, segredos de cliente e tokens como credenciais opacas. Repetir uma troca interrompida com as mesmas entradas é rejeitado como concessão inválida. Reinicie a concessão.

Um código de autorização expira 10 minutos após sua emissão, um token de acesso após 7 dias e um token de atualização após 30 dias. Cada troca de atualização emite um novo token de atualização que expira 30 dias após sua emissão, portanto uma concessão termina 30 dias após sua última atualização.

Autenticação de rota

Toda rota nesta página que autentica um usuário é exclusiva de usuário, exceto quando a operação diz o contrário. O Decoding Chat rejeita token de bot e bearer OAuth2 com 403 ACCESS_DENIED, e aceita conta com ação obrigatória pendente. As rotas de token, introspecção e revogação autenticam o aplicativo cliente, portanto seu rate limit tem como chave o endereço IP do cliente.

Normalização de strings OAuth2

O Decoding Chat apara todo campo de string OAuth2 delimitado antes de verificar seu comprimento. Cada campo desse tipo aceita de 1 a 256 unidades de código UTF-16, incluindo redirect_uri. O Decoding Chat valida, armazena, compara, encaminha e retorna o valor normalizado. O campo permissions e o campo response_type de Conceder consentimento OAuth2 são lidos literalmente e não têm limite de comprimento próprio. As credenciais HTTP Basic do cliente não passam por esta normalização de campo de requisição. O code_challenge e o code_verifier PKCE também são normalizados, portanto um cliente NÃO DEVE depender de espaços em branco adjacentes sobreviverem.

Escopos OAuth2

Um escopo nomeia uma coisa que o aplicativo pode ler ou fazer em nome do usuário.

Valor	Descrição
identify¹	Ler a identidade da conta do usuário autorizado
email²	Incluir o endereço de e-mail e o estado de verificação do usuário autorizado
guilds³	Ler os servidores dos quais o usuário autorizado é membro
connections⁴	Ler as conexões do usuário autorizado
bot⁵	Instalar a conta bot do aplicativo em um servidor ou mensagem direta em grupo selecionado

¹ Concede Obter informações do usuário OAuth2 e a representação bearer reduzida de Obter usuário atual, e também é necessário antes que Obter autorização OAuth2 atual inclua um objeto de usuário

² Não tem efeito observável a menos que identify também seja concedido, pois toda rota que expõe o endereço também requer identify

³ Concede Listar servidores do usuário atual, Obter servidor e Listar cargos do servidor

⁴ Concede Listar conexões

⁵ Instala uma conta bot e não concede acesso bearer próprio, portanto uma aplicação cujas concessões são apenas bot nunca é apresentada como autorização por Listar autorizações OAuth2

Um valor de escopo não reconhecido é rejeitado quando a requisição de autorização é completada. O Decoding Chat divide uma string de escopo em sequências de espaços em branco e caracteres +, e descarta segmentos vazios. Um valor de escopo repetido é concedido uma vez.

O Decoding Chat ordena a string scope de um token OAuth2 e de uma introspecção OAuth2 na ordem do registro acima. O array scopes de uma autorização OAuth2 atual tem os escopos armazenados em nenhuma ordem definida, com valores não reconhecidos removidos. O array scopes de uma autorização OAuth2 está em nenhuma ordem definida, e pode conter bot ou um valor não reconhecido quando o usuário possui mais de um token de atualização ativo para o aplicativo.

Objeto de resposta de erro OAuth2

O envelope de falha que as rotas OAuth2 retornam.

Estrutura

Campo	Tipo	Descrição
error	string	O código de erro OAuth2 que nomeia a falha
error_description¹	string	A descrição legível da falha

¹ Sempre presente, e algumas descrições são um identificador de código de erro de API simples

Esses membros são o corpo inteiro, portanto o corpo não tem os membros code e message da resposta de erro comum. O Decoding Chat retorna toda falha OAuth2 com status 400. Um cliente DEVE usar error como chave e nunca error_description.

As rotas de consentimento, token, introspecção e revogação retornam este objeto para uma falha de concessão, autenticação de cliente, escopo, redirecionamento, tipo de resposta ou máscara de permissão. Toda outra falha, incluindo validação de requisição, autenticação, autorização e rate limiting, usa a resposta de erro comum com um código de erro da API.

Exemplo

{
  "error": "invalid_grant",
  "error_description": "Authorization code is invalid or expired"
}

Códigos de erro OAuth2

Valor	Descrição
invalid_request²	A própria requisição está malformada
invalid_client³	A autenticação do cliente falhou
invalid_grant⁴	A concessão apresentada não é utilizável
invalid_scope	O escopo solicitado contém um valor que não está no registro de escopos

² O URI de redirecionamento está ausente, não registrado ou não analisável, o tipo de resposta não é code em uma requisição que solicita escopo não-bot, a máscara de permissão solicitada não é um literal inteiro não negativo, ou as credenciais de cliente são fornecidas tanto em cabeçalho Authorization quanto no formulário

³ O aplicativo cliente é desconhecido, não forneceu segredo de cliente, ou forneceu segredo que não corresponde ao hash armazenado

⁴ O código de autorização ou token de atualização é desconhecido, expirado, já usado, vinculado a outro aplicativo, ou vinculado a outro URI de redirecionamento, ou o código de autorização tem desafio PKCE que o verificador apresentado não corresponde

Objeto de token OAuth2

O par de tokens de acesso e atualização que uma troca de token bem-sucedida retorna.

Estrutura

Campo	Tipo	Descrição
access_token	string	O token bearer que o aplicativo apresenta no cabeçalho `Authorization`
token_type	string	O tipo de token, sempre `Bearer`
expires_in¹	integer	O tempo de vida do token de acesso em segundos, sempre 604800
refresh_token²	string	O token de atualização que substitui este par quando trocado
scope	string	Os escopos concedidos, separados por espaço na ordem do registro

¹ O tempo de vida do token de acesso configurado, repetido em cada resposta bem-sucedida

² Toda concessão que o Decoding Chat emite está vinculada a um usuário, portanto uma troca bem-sucedida sempre retorna token de atualização

Exemplo

{
  "access_token": "M2xQb1RkY0hqTmZLc1B2WndBcUx1RWc2WXRJbk9iUmE",
  "token_type": "Bearer",
  "expires_in": 604800,
  "refresh_token": "VGhpc0lzQUZha2VSZWZyZXNoVG9rZW5Gb3JEb2NzMDE",
  "scope": "identify email"
}

Objeto de informações do usuário OAuth2

A identidade de conta que um aplicativo lê com o escopo identify.

Estrutura

Campo	Tipo	Descrição
sub	snowflake	O ID do usuário sujeito, igual a `id`
id	snowflake	O ID da conta
username	string	O nome de usuário da conta
discriminator	string	O tag discriminador de quatro dígitos
global_name	?string	O nome de exibição da conta, ou null quando não definido
avatar¹	?string	O hash do avatar da conta, ou null quando não tem
email?²	?string	O endereço de e-mail da conta, null a menos que o escopo `email` seja concedido e haja endereço definido
verified?³	?boolean	Se o endereço foi verificado
flags?⁴	integer	Os flags públicos de usuário na conta
avatar_color⁵	?integer	A cor padrão do avatar
bot⁵	boolean	Se a conta é um bot
system⁵	boolean	Se a conta é um usuário de sistema

¹ Um hash de avatar animado tem o prefixo a_, e o prefixo é removido enquanto a conta não tem direito a avatar animado

² Sempre emitido

³ Emitido apenas quando o escopo email é concedido e a conta tem endereço. Um endereço não verificado reporta false

⁴ Declarado opcional pelo schema de resposta e emitido em cada resposta

⁵ Emitido em cada resposta embora o schema de resposta não o declare, portanto um cliente NÃO DEVE depender disso

Objeto de introspecção OAuth2

O relatório de vivacidade e escopo que o Decoding Chat retorna para um token apresentado.

Estrutura

Campo	Tipo	Descrição
active	boolean	Se o token apresentado está ativo e pertence ao cliente autenticado
scope?	string	Os escopos concedidos, separados por espaço na ordem do registro
client_id?	snowflake	O ID do aplicativo para o qual o token foi emitido
username?¹	string	Um membro reservado que o Decoding Chat nunca define
token_type?	string	O tipo de token apresentado, `Bearer` para token de acesso e `refresh_token` para token de atualização
exp?²	integer	O tempo de expiração do token de acesso em segundos Unix
iat?	integer	O tempo de emissão em segundos Unix
sub?³	snowflake	O ID do usuário sujeito

¹ Ausente de cada resposta

² Ausente para token de atualização, que ainda expira 30 dias após sua emissão

³ Todo token que o Decoding Chat emite está vinculado a um usuário, portanto um resultado ativo sempre tem um sujeito

Exceto por username e exp, todo campo opcional acima está presente quando active é true e ausente quando é false. Um token de acesso ativo tem exp e um token de atualização ativo não tem.

O Decoding Chat reporta um token desconhecido, um token expirado e um token emitido para outro aplicativo como inativos. Um corpo inativo tem apenas active definido como false, e não nomeia motivo. O Decoding Chat não consulta a conta do usuário durante a introspecção, portanto um resultado ativo descreve apenas o token e nada diz sobre o estado daquela conta.

Objeto de autorização OAuth2 atual

O aplicativo, os escopos e a expiração por trás do token de acesso que o chamador apresentou.

Estrutura

Campo	Tipo	Descrição
application	resumo de aplicação OAuth2 object	O aplicativo para o qual o token de acesso foi emitido
scopes¹	array[string]	Os escopos concedidos, com valores não reconhecidos removidos
expires	timestamp ISO8601	O tempo de expiração do token de acesso
user?²	usuário autorizado OAuth2 object	A conta para a qual o token de acesso foi emitido

¹ Emitido em nenhuma ordem definida, e bot permanece no array mesmo que não conceda acesso bearer

² Presente apenas quando o token concede identify e a conta ainda existe, portanto um token restrito a bot nunca tem um

Objeto de resumo de aplicação OAuth2

O registro de aplicação reduzido em uma autorização OAuth2 atual.

Estrutura

Campo	Tipo	Descrição
id	snowflake	O ID do aplicativo
name	string	O nome do aplicativo
icon¹	?string	O hash do ícone, sempre null neste objeto
description¹	?string	A descrição, sempre null neste objeto
bot_public	boolean	Se qualquer usuário elegível pode instalar o bot
bot_require_code_grant	boolean	Se a instalação do bot requer concessão de código OAuth2
flags²	integer	Os flags do aplicativo, sempre 0

¹ Null mesmo quando o bot do aplicativo tem avatar ou bio

² Nenhum bit de flag de aplicativo está definido

Objeto de usuário autorizado OAuth2

A conta para a qual uma autorização OAuth2 atual foi emitida.

Estrutura

Campo	Tipo	Descrição
id	snowflake	O ID da conta
username	string	O nome de usuário da conta
discriminator	string	O tag discriminador de quatro dígitos
global_name	?string	O nome de exibição da conta, ou null quando não definido
avatar¹	?string	O hash do avatar da conta, ou null quando não tem
avatar_color	?integer	A cor padrão do avatar
bot?²	boolean	Se a conta é um bot
system?²	boolean	Se a conta é um usuário de sistema
flags	integer	Os flags públicos de usuário na conta
email?³	?string	O endereço de e-mail da conta, null a menos que o escopo `email` seja concedido e haja endereço definido
verified?⁴	?boolean	Se o endereço foi verificado
sub⁵	snowflake	O ID do usuário sujeito, igual a `id`

¹ Um hash de avatar animado tem o prefixo a_, e o prefixo é removido enquanto a conta não tem direito a avatar animado

² Emitido em cada resposta, e false quando a conta não é nenhum dos dois

³ Sempre emitido

⁴ Emitido apenas quando o escopo email é concedido e a conta tem endereço

⁵ Emitido em cada resposta embora o schema de resposta não o declare, portanto um cliente NÃO DEVE depender disso

Objeto de autorização OAuth2

Um aplicativo que o usuário atual autorizou, agregado por seus tokens de atualização ativos.

Estrutura

Campo	Tipo	Descrição
application	aplicação autorizada object	O aplicativo ao qual o usuário concedeu acesso
scopes¹	array[string]	Os escopos agregados dos tokens de atualização ativos do usuário para o aplicativo
authorized_at²	timestamp ISO8601	O tempo de criação mais antigo entre os tokens de atualização que contribuíram para esta entrada

¹ Os escopos não têm ordem definida e podem incluir bot ou valor não reconhecido. Ignore valores não reconhecidos

² O tempo de emissão mais antigo entre as concessões de atualização atuais do aplicativo

Uma autorização aparece apenas enquanto o aplicativo possui uma concessão de atualização ativa com um escopo reconhecido diferente de bot.

Objeto de aplicação autorizada

O aplicativo nomeado por uma entrada de autorização OAuth2.

Estrutura

Campo	Tipo	Descrição
id	snowflake	O ID do aplicativo
name	string	O nome do aplicativo
icon¹	?string	O hash do avatar da conta bot do aplicativo
description²	?string	A descrição, sempre null neste objeto
bot_public	boolean	Se qualquer usuário elegível pode instalar o bot

¹ Null quando o aplicativo não tem conta bot ou essa conta não tem avatar. O hash armazenado é reportado sem filtro, portanto um hash animado mantém seu prefixo a_

² Um registro de aplicação não tem campo de descrição, portanto este valor é sempre null

Objeto de resposta de consentimento OAuth2

A URL de callback que Conceder consentimento OAuth2 retorna após registrar a decisão.

Estrutura

Campo	Tipo	Descrição
redirect_to¹	string	A URL absoluta com o resultado da autorização

¹ A URL tem o parâmetro de consulta code, e o state normalizado do chamador quando fornecido

O Decoding Chat constrói a URL a partir do URI de redirecionamento registrado que a requisição resolveu, que é a URL do aplicativo web configurada quando uma autorização apenas-bot não forneceu nenhum. O código registra a serialização de URL daquele URI resolvido, e o cliente apresenta exatamente aquela serialização a Trocar token OAuth2.

Autorizar aplicação

GET/v1/oauth2/authorize

Unauthenticated

Inicia uma requisição de autorização. O Decoding Chat retorna redirecionamento para toda consulta que passa na validação de requisição. A autenticação é opcional.

Parâmetros de consulta

Campo	Tipo	Descrição
response_type?	string	O tipo de resposta OAuth2, `code` quando fornecido
client_id	snowflake	O ID do aplicativo sendo autorizado
redirect_uri?¹	string	O URI de redirecionamento absoluto registrado pelo aplicativo (1-256 unidades de código UTF-16 após normalização)
scope	string	Os escopos OAuth2 solicitados, separados por espaço (1-256 unidades de código UTF-16 após normalização)
state?⁴	string	O estado do chamador (1-256 unidades de código UTF-16 após normalização)
prompt?	string	O modo de prompt, `consent` ou `none`
guild_id?²	snowflake	O servidor pré-selecionado para o escopo `bot`
channel_id?²	snowflake	A mensagem direta em grupo pré-selecionada para o escopo `bot`
permissions?³	string	O literal inteiro de permissão do bot
disable_guild_select?	string	Se a interface de consentimento suprime a seleção de servidor, como literal `true` ou `false`
code_challenge?	string	O desafio PKCE vinculado ao código emitido (1-256 unidades de código UTF-16 após normalização)
code_challenge_method?	string	O método PKCE, `S256` ou `plain`, com padrão `plain` quando desafio é fornecido sem ele

¹ O valor deve ser analisável como URL absoluta com esquema e host, e deve corresponder a um URI de redirecionamento registrado antes que um código seja emitido

² Ambos os valores são encaminhados para a interface de consentimento inalterados, e apenas Conceder consentimento OAuth2 rejeita uma requisição que fornece ambos

³ O valor é encaminhado para a interface de consentimento inalterado e é analisado como inteiro apenas por Conceder consentimento OAuth2

⁴ O valor é retornado inalterado após normalização, tanto no redirecionamento de sucesso quanto no de erro

Resposta

Status	Corpo	Condição
302	vazio	A interface de consentimento, callback bem-sucedido ao cliente ou callback de erro OAuth2 foi selecionado

O cabeçalho Location do 302 é o redirecionamento selecionado.

Sem prompt=none, o redirecionamento aponta para a interface de consentimento do Decoding Chat e encaminha cada parâmetro fornecido, portanto nenhuma validação de aplicação, escopo ou redirecionamento ocorre ainda.

Com prompt=none, uma requisição que não resolve nenhum usuário redireciona com error=login_required. Toda outra falha silenciosa redireciona com error=consent_required. Isso cobre toda falha de emissão de código, incluindo aplicação desconhecida, escopo não reconhecido, URI de redirecionamento ausente ou não registrado, e bot privado que o chamador não possui. Também cobre um escopo não-bot solicitado que o usuário ainda não concedeu a este aplicativo. Uma requisição silenciosa que solicita apenas bot ignora o teste de concessão anterior.

Um redirecionamento de erro tem error e o state normalizado quando o chamador forneceu um, mas sem error_description e nunca o código de erro OAuth2 mais específico que a falha subjacente gerou.

O Decoding Chat compara as duas strings byte a byte, portanto esquema, porta, barra final, consulta ou fragmento diferentes não correspondem. Todo outro caso redireciona para a URL configurada do aplicativo web do Decoding Chat. Isso cobre um URI de redirecionamento omitido, um aplicativo desconhecido e um aplicativo sem URI registrado.

Efeitos colaterais

Uma requisição prompt=none bem-sucedida emite um código de autorização vinculado ao aplicativo, usuário, URI de redirecionamento resolvido, escopos concedidos e desafio PKCE. O código expira após 10 minutos. Nada mais muda. Apenas Conceder consentimento OAuth2 instala um bot.

Rate limit

60 requisições por minuto para cada usuário autenticado, ou para cada endereço IP do cliente quando a requisição não tem credencial, no bucket oauth:authorize.

Conceder consentimento OAuth2

POST/v1/oauth2/authorize/consent

Completa uma requisição de autorização. Retorna um objeto resposta de consentimento OAuth2 com a URL de callback.

Instalar um bot em um servidor requer MANAGE_GUILD ou ADMINISTRATOR naquele servidor. Instalá-lo em uma mensagem direta em grupo requer que o chamador seja destinatário daquele canal.

Uma instalação em servidor emite Guild Create, Guild Member Add e, a menos que o servidor suprima notificações de entrada, Message Create. Quando uma máscara de permissão diferente de zero é solicitada, também emite Guild Role Create e Guild Member Update. Uma instalação em mensagem direta em grupo emite Channel Create para o bot, Channel Recipient Add para os destinatários existentes e Message Create.

Corpo JSON

Campo	Tipo	Descrição
response_type?¹	string	O tipo de resposta OAuth2
client_id	snowflake	O ID do aplicativo sendo autorizado
redirect_uri?²	string	O URI de redirecionamento absoluto registrado pelo aplicativo (1-256 unidades de código UTF-16 após normalização)
scope	string	Os escopos OAuth2 solicitados, separados por espaço (1-256 unidades de código UTF-16 após normalização)
state?	string	O estado do chamador adicionado à URL de callback (1-256 unidades de código UTF-16 após normalização)
permissions?³	string	O literal inteiro de permissão do bot solicitado para o bot instalado
guild_id?⁴	snowflake	O servidor onde o bot é instalado
channel_id?⁴	snowflake	A mensagem direta em grupo onde o bot é instalado
code_challenge?	string	O desafio PKCE vinculado ao código emitido (1-256 unidades de código UTF-16 após normalização)
code_challenge_method?	string	O método PKCE, `S256` ou `plain`, com padrão `plain` quando desafio é fornecido sem ele

¹ Em uma requisição que solicita qualquer escopo diferente de bot, um valor omitido assume code como padrão e um fornecido deve ser code. Em uma requisição que solicita apenas o escopo bot, o campo é ignorado

² Obrigatório a menos que a requisição solicite apenas o escopo bot, e deve corresponder a um URI de redirecionamento registrado. Uma requisição apenas-bot ainda o requer quando o aplicativo define bot_require_code_grant

³ O valor deve ser analisável como literal inteiro não negativo. Todo bit fora da máscara de permissão definida é limpo antes do uso, e um chamador sem ADMINISTRATOR não pode solicitar um bit retido que não possui

⁴ Os campos são mutuamente exclusivos

Resposta

Status	Corpo	Condição
200	resposta de consentimento OAuth2 object	Consentimento concluído
400⁵	resposta de erro	O corpo falha na validação, ou o alvo de instalação do bot não é utilizável
400⁶	erro OAuth2 object	O aplicativo, escopo, URI de redirecionamento, tipo de resposta ou máscara de permissão é rejeitado
403⁷	resposta de erro	A credencial ou as permissões do chamador não permitem a instalação
404	resposta de erro	O canal selecionado não existe (`UNKNOWN_CHANNEL`) ou o servidor selecionado não existe (`UNKNOWN_GUILD`)

⁵ Ambos os alvos de instalação são fornecidos, o canal selecionado não é mensagem direta em grupo (INVALID_CHANNEL_TYPE), o aplicativo não tem bot (NOT_A_BOT_APPLICATION), o bot já é membro do servidor selecionado (BOT_ALREADY_IN_GUILD), o servidor atingiu o limite de membros (MAX_GUILD_MEMBERS) ou de cargos (MAX_GUILD_ROLES), ou a mensagem direta em grupo atingiu o limite de destinatários (MAX_GROUP_DM_RECIPIENTS)

⁶ O aplicativo é desconhecido, um escopo não é reconhecido, o URI de redirecionamento está ausente ou não registrado, o tipo de resposta não é code em uma requisição que solicita escopo não-bot, ou a máscara de permissão não é literal inteiro não negativo

⁷ A credencial é token de bot ou bearer OAuth2 (ACCESS_DENIED), o bot é privado e o chamador não possui o aplicativo (BOT_IS_PRIVATE), o chamador não tem MANAGE_GUILD nem ADMINISTRATOR no servidor selecionado, ou solicita bit de permissão que não possui (MISSING_PERMISSIONS), ou o chamador não é destinatário do canal selecionado (MISSING_ACCESS)

Efeitos colaterais

O consentimento emite um código de autorização vinculado ao aplicativo, usuário, URI de redirecionamento resolvido, escopos concedidos e desafio PKCE, e retorna a URL de callback que o contém.

Com o escopo bot e alvo de servidor, o consentimento adiciona o bot ao servidor com origem de entrada bot-invite e o chamador registrado como convidante. O consentimento contorna o limite de servidores da conta bot e a lista de banimentos do servidor. O limite de membros do servidor ainda se aplica. Quando uma máscara de permissão diferente de zero é solicitada, o consentimento também cria um cargo com exatamente a máscara de permissão filtrada, nomeia o cargo após o aplicativo e o atribui ao bot. A instalação ou tem êxito com exatamente aquela máscara ou falha com erro de permissões ausentes.

Aquele cargo é criado na posição 1 sem cor e não está com exibição destacada nem é mencionável. Ele consome uma vaga de cargo do servidor e não é removido quando o bot sai. A instalação registra entradas de log de auditoria de adição de bot, criação de cargo e atualização de cargo de membro.

Com o escopo bot e alvo de mensagem direta em grupo, o consentimento adiciona o bot como destinatário e armazena a mensagem de sistema de adição de destinatário.

Quando qualquer parte da instalação falha, o Decoding Chat cancela o código de autorização recém-emitido, portanto o chamador nunca recebe código utilizável.

Rate limit

60 requisições por minuto para cada usuário autenticado, no bucket oauth:authorize.

Trocar token OAuth2

POST/v1/oauth2/token

Troca um código de autorização ou token de atualização. Retorna um objeto token OAuth2 em caso de sucesso.

O corpo da requisição é application/x-www-form-urlencoded ou multipart/form-data. O aplicativo cliente autentica-se com HTTP Basic ou com os campos de formulário client_id e client_secret. Nenhuma credencial de usuário é aceita.

Tokens de acesso emitidos anteriormente para o mesmo usuário e aplicativo permanecem válidos após uma atualização. Cada um expira 7 dias após sua emissão.

Cabeçalhos da requisição

Campo	Tipo	Descrição
Authorization?¹	string	As credenciais HTTP Basic do cliente
Content-Type	string	O tipo de mídia da requisição, `application/x-www-form-urlencoded` ou `multipart/form-data`

¹ Esta rota resolve o cliente a partir do formulário primeiro e usa o cabeçalho como fallback, portanto fornecer ambos é aceito. As rotas de introspecção e revogação rejeitam aquela combinação como invalid_request

Corpo do formulário

Campos de código de autorização

Campo	Tipo	Descrição
grant_type	string	O tipo de concessão, sempre `authorization_code` nesta variante
code	string	O código de autorização retornado pelo callback (1-256 unidades de código UTF-16 após normalização)
redirect_uri¹	string	O URI de redirecionamento que a requisição de autorização resolveu (1-256 unidades de código UTF-16 após normalização)
client_id?²	snowflake	O ID do cliente, que tem precedência sobre o valor HTTP Basic
client_secret?²	string	O segredo do cliente, que tem precedência sobre o valor HTTP Basic (1-256 unidades de código UTF-16 após normalização)
code_verifier?³	string	O verificador PKCE provando o desafio armazenado no código (1-256 unidades de código UTF-16 após normalização)

¹ Comparado como string exata com o URI registrado no código, que a resposta de consentimento OAuth2 descreve. Uma barra final, capitalização de host ou diferença de codificação percentual diferente é rejeitado como concessão inválida

² Cada campo de credencial é resolvido por conta própria, portanto um valor de formulário é usado quando fornecido e o valor HTTP Basic é usado caso contrário, e um client_id de formulário pode ser combinado com segredo de cliente HTTP Basic. Uma requisição que não resolve ID de cliente ou segredo de cliente é rejeitada como invalid_client

³ Obrigatório quando o código de autorização tem desafio PKCE. Para o método S256, é hasheado com SHA-256 e codificado em base64url antes da comparação com o desafio armazenado no código; para plain, é comparado inalterado

Quando o código tem vínculo PKCE, um verificador ausente ou incorreto é rejeitado como invalid_grant na resposta de erro OAuth2.

Campos de token de atualização

Campo	Tipo	Descrição
grant_type	string	O tipo de concessão, sempre `refresh_token` nesta variante
refresh_token	string	O token de atualização a trocar (1-256 unidades de código UTF-16 após normalização)
client_id?¹	snowflake	O ID do cliente, que tem precedência sobre o valor HTTP Basic
client_secret?¹	string	O segredo do cliente, que tem precedência sobre o valor HTTP Basic (1-256 unidades de código UTF-16 após normalização)

¹ Cada campo de credencial é resolvido por conta própria, portanto um valor de formulário é usado quando fornecido e o valor HTTP Basic é usado caso contrário, e um client_id de formulário pode ser combinado com segredo de cliente HTTP Basic. Uma requisição que não resolve ID de cliente ou segredo de cliente é rejeitada como invalid_client

Resposta

Status	Corpo	Condição
200	token OAuth2 object	Um par de tokens foi emitido
400	resposta de erro	O formulário falha na validação, incluindo `grant_type` não suportado
400²	erro OAuth2 object	A autenticação do cliente ou a concessão apresentada falha

² Autenticação do cliente, código de autorização, token de atualização, URI de redirecionamento ou verificador PKCE necessário está ausente ou não corresponde à concessão

Um código de autorização é de uso único. O Decoding Chat o consome antes de emitir o par de tokens. Um código repetido é rejeitado como concessão inválida. Excluir uma conta purga todos os tokens de acesso e atualização OAuth2 que ela possui, portanto uma troca de atualização para conta excluída é rejeitada como concessão inválida. Um código de autorização emitido antes da exclusão ainda pode ser trocado até expirar.

O Decoding Chat verifica a autenticação do cliente antes de verificar a concessão, portanto aplicativo desconhecido, segredo de cliente ausente e segredo de cliente errado são todos reportados como invalid_client.

Qualquer outro grant_type, incluindo client_credentials, falha na validação de requisição com a resposta de erro comum.

Efeitos colaterais

Uma troca bem-sucedida emite um token de acesso que expira após 7 dias e um token de atualização que expira após 30 dias. Uma troca de código de autorização consome o código, e uma troca de atualização consome o token de atualização apresentado. Nada mais muda e nenhum Dispatch Gateway é emitido.

Rate limit

120 requisições por minuto para cada endereço IP do cliente, no bucket oauth:token.

Obter informações do usuário OAuth2

GET/v1/oauth2/userinfo

identify

Retorna o objeto informações do usuário OAuth2 para a conta para a qual o token foi emitido. Requer o escopo identify.

Um token de acesso bearer OAuth2 é necessário. O escopo email preenche os campos de endereço.

Cabeçalhos da requisição

Campo	Tipo	Descrição
Authorization	string	O token de acesso bearer OAuth2

Resposta

Status	Corpo	Condição
200	informações do usuário OAuth2 object	As informações do usuário foram retornadas
401¹	resposta de erro	O token bearer está ausente, inutilizável ou expirado
403	resposta de erro	O token não tem `identify` (`MISSING_OAUTH_SCOPE`)

¹ A credencial está ausente, não é token de acesso bearer OAuth2, ou expirou (UNAUTHORIZED), ou o bearer não resolve mais um usuário e um aplicativo (INVALID_TOKEN)

Uma falha de escopo ausente tem o escopo necessário como membro de nível superior required_scope da resposta de erro, para que um cliente possa solicitar a autorização correta sem analisar o texto da mensagem.

Rate limit

120 requisições por minuto para cada par de usuário autenticado e aplicação bearer, no bucket oauth:introspect.

Introspectar token OAuth2

POST/v1/oauth2/introspect

Retorna um objeto introspecção OAuth2 descrevendo um token de acesso ou atualização.

Cabeçalhos da requisição

Campo	Tipo	Descrição
Authorization?	string	As credenciais HTTP Basic do cliente
Content-Type	string	O tipo de mídia da requisição, `application/x-www-form-urlencoded` ou `multipart/form-data`

Corpo do formulário

Campo	Tipo	Descrição
token	string	O token de acesso ou atualização a inspecionar (1-256 unidades de código UTF-16 após normalização)
client_id?¹	snowflake	O ID do cliente, fornecido quando HTTP Basic não é usado
client_secret?¹	string	O segredo do cliente, fornecido quando HTTP Basic não é usado (1-256 unidades de código UTF-16 após normalização)

¹ Fornecer qualquer campo junto com cabeçalho Authorization HTTP Basic bem formado é rejeitado como invalid_request

Resposta

Status	Corpo	Condição
200	introspecção OAuth2 object	Introspecção concluída, incluindo token reportado como inativo
400	resposta de erro	O formulário falha na validação
400²	erro OAuth2 object	A autenticação do cliente falhou

² Credenciais de cliente fornecidas tanto no cabeçalho quanto no formulário (invalid_request), nenhum segredo de cliente fornecido, cliente desconhecido ou segredo de cliente errado (invalid_client)

O Decoding Chat ignora cabeçalho Authorization que não é HTTP Basic bem formado e lê as credenciais do cliente do formulário.

Apenas um token emitido para o cliente autenticado é reportado como ativo.

Rate limit

120 requisições por minuto para cada endereço IP do cliente, no bucket oauth:introspect.

Revogar token OAuth2

POST/v1/oauth2/token/revoke

Revoga um token de acesso ou atualização apresentado.

Cabeçalhos da requisição

Campo	Tipo	Descrição
Authorization?	string	As credenciais HTTP Basic do cliente
Content-Type	string	O tipo de mídia da requisição, `application/x-www-form-urlencoded` ou `multipart/form-data`

Corpo do formulário

Campo	Tipo	Descrição
token	string	O token de acesso ou atualização a revogar (1-256 unidades de código UTF-16 após normalização)
token_type_hint?¹	string	O tipo de token apresentado, `access_token` ou `refresh_token`
client_id?²	snowflake	O ID do cliente, fornecido quando HTTP Basic não é usado
client_secret?²	string	O segredo do cliente, fornecido quando HTTP Basic não é usado (1-256 unidades de código UTF-16 após normalização)

¹ Um hint refresh_token faz o Decoding Chat procurar primeiro um token de atualização correspondente, depois um token de acesso correspondente quando nenhum token de atualização corresponde. Um hint ausente e um hint access_token fazem o Decoding Chat procurar apenas token de acesso correspondente

² Fornecer qualquer campo junto com cabeçalho Authorization HTTP Basic bem formado é rejeitado como invalid_request

Um cliente que apresenta token de atualização DEVE enviar token_type_hint=refresh_token, ou o Decoding Chat não corresponde a nenhum token e não exclui nada.

Resposta

Status	Corpo	Condição
200	vazio	A requisição de revogação foi processada, incluindo token que não correspondeu a nada
400	resposta de erro	O formulário falha na validação
400³	erro OAuth2 object	A autenticação do cliente falhou

³ Credenciais de cliente fornecidas tanto no cabeçalho quanto no formulário (invalid_request), nenhum segredo de cliente fornecido, cliente desconhecido ou segredo de cliente errado (invalid_client)

O Decoding Chat ignora cabeçalho Authorization que não é HTTP Basic bem formado e lê as credenciais do cliente do formulário.

Um token desconhecido e um token emitido para outro aplicativo retornam 200, portanto a resposta nunca mostra se um token existe.

Efeitos colaterais

Em uma correspondência, o Decoding Chat exclui o conjunto completo de tokens do usuário para o aplicativo autenticado. Esses tokens param de autenticar requisições imediatamente. Um token que não correspondeu a nada não muda nenhum estado.

Nenhum Dispatch Gateway é emitido, portanto um cliente com token revogado toma conhecimento da revogação pela sua próxima requisição rejeitada.

Rate limit

120 requisições por minuto para cada endereço IP do cliente, no bucket oauth:introspect.

Obter autorização OAuth2 atual

GET/v1/oauth2/@me

Retorna o objeto autorização OAuth2 atual para o token de acesso apresentado. Não requer escopo.

Um token de acesso bearer OAuth2 é necessário, e o token deve pertencer a conta não-bot. A resposta tem objeto de usuário apenas quando o token possui identify.

Cabeçalhos da requisição

Campo	Tipo	Descrição
Authorization	string	O token de acesso bearer OAuth2

Resposta

Status	Corpo	Condição
200	autorização OAuth2 atual object	A autorização foi retornada
401¹	resposta de erro	O token bearer está ausente, inutilizável ou expirado
403	resposta de erro	O token pertence a conta bot (`ACCESS_DENIED`)

¹ A credencial está ausente, não é token de acesso bearer OAuth2, ou expirou (UNAUTHORIZED), o bearer não tem identidade de usuário (UNAUTHORIZED), ou nomeia aplicativo que não existe mais (INVALID_TOKEN)

Rate limit

120 requisições por minuto para cada par de usuário autenticado e aplicação bearer, no bucket oauth:introspect.

Listar autorizações OAuth2

GET/v1/oauth2/@me/authorizations

Retorna os objetos autorização OAuth2 que o usuário atual concedeu a aplicações.

Resposta

Status	Corpo	Condição
200	array[autorização OAuth2 object]	As autorizações foram retornadas
403	resposta de erro	A credencial é token de bot ou bearer OAuth2 (`ACCESS_DENIED`)

Uma aplicação aparece na listagem apenas enquanto possui concessão de atualização ativa com escopo reconhecido diferente de bot. Uma aplicação excluída é omitida. A listagem não tem paginação.

Rate limit

60 requisições por minuto para cada usuário autenticado, no bucket oauth_dev:clients:list.

Revogar autorização OAuth2

DELETE/v1/oauth2/@me/authorizations/{applicationId}

Revoga a autorização do usuário atual para um aplicativo.

Parâmetros de caminho

Campo	Tipo	Descrição
applicationId	snowflake	O ID do aplicativo cuja autorização é revogada

Resposta

Status	Corpo	Condição
204	vazio	A autorização foi revogada, inclusive quando nenhuma concessão restava
400	resposta de erro	O ID do aplicativo não é snowflake válido
403	resposta de erro	A credencial é token de bot ou bearer OAuth2 (`ACCESS_DENIED`)
404	resposta de erro	O aplicativo não existe (`UNKNOWN_APPLICATION`)

O Decoding Chat resolve o aplicativo antes de excluir qualquer token, portanto um 404 deixa a concessão intocada.

Efeitos colaterais

A revogação exclui todos os tokens de acesso e atualização que o usuário atual possui para o aplicativo nomeado. Esses tokens param de autenticar requisições imediatamente.

Um bot que o aplicativo instalou permanece em cada servidor e mensagem direta em grupo que ingressou. Nenhum Dispatch Gateway é emitido.

Rate limit

120 requisições por minuto para cada usuário autenticado, no bucket oauth:introspect.

Revogar várias autorizações OAuth2

POST/v1/oauth2/@me/authorizations/revoke

Revoga as autorizações do usuário atual para vários aplicativos.

Corpo JSON

Campo	Tipo	Descrição
application_ids¹	array[snowflake]	Os IDs das aplicações a revogar (1-100)

¹ IDs repetidos são consolidados antes de qualquer revogação

Resposta

Status	Corpo	Condição
204	vazio	As autorizações foram revogadas
400	resposta de erro	O corpo falha na validação, incluindo array de IDs vazio ou muito grande
403	resposta de erro	A credencial é token de bot ou bearer OAuth2 (`ACCESS_DENIED`)
404	resposta de erro	Um dos aplicativos nomeados não existe (`UNKNOWN_APPLICATION`)

O Decoding Chat resolve cada aplicativo nomeado antes de excluir qualquer token. Um aplicativo desconhecido deixa cada aplicativo nomeado intocado.

Efeitos colaterais

A revogação exclui todos os tokens de acesso e atualização que o usuário atual possui para cada aplicativo nomeado. Esses tokens param de autenticar requisições imediatamente. As associações de bot não são afetadas e nenhum Dispatch Gateway é emitido.

Rate limit

120 requisições por minuto para cada usuário autenticado, no bucket oauth:introspect.