Recurso de autenticação

O recurso de Autenticação cobre cadastro, login, recuperação de conta e transferência de sessão para um novo dispositivo. Todas as rotas nesta página estão sob /v1/auth.

Comportamento compartilhado

Autenticação e Autenticação HTTP definem a sintaxe de credenciais e os namespaces de credenciais. A alteração das credenciais de uma conta que já está conectada é coberta por Alterações de e-mail e senha, Autenticação multifator e Verificação de telefone.

O material de autenticação é confidencial e opaco

Um cliente DEVE tratar cada token de sessão, token de uso único, ticket, estado de SSO e código de handoff como confidencial. Ele NÃO DEVE analisá-lo, expô-lo a código não confiável ou gravá-lo em logs, análises ou em um URL que a operação não atribuiu.

A maioria das operações não precisa de uma credencial de Authorization, porque a solicitação tem um token de uso único, ticket de MFA, asserção WebAuthn ou credencial de conta própria. Listar sessões de autenticação, encerrar sessões de autenticação, reenviar verificação de e-mail, sair e concluir handoff para desktop são as únicas operações nesta página que leem uma credencial de Authorization. O handoff completo para desktop lê o cabeçalho apenas quando seu corpo omite o campo token. As três primeiras requerem uma sessão de usuário comum, e cada uma rejeita um token de bot e um token bearer OAuth2 com 403 ACCESS_DENIED. Todas as três ainda admitem uma sessão cuja conta está sinalizada por atividade suspeita.

Cada rota tem um bucket de rota e também está sujeita ao limite HTTP global. Um bucket de rota é chaveado pelo usuário autenticado quando a solicitação tem uma credencial resolúvel e pelo endereço IP do cliente caso contrário. A negação do bucket ou global retorna 429 RATE_LIMITED.

Uma forma JSON inválida retorna 400 INVALID_FORM_BODY com entradas de objeto de erro de validação em errors. Uma falha inesperada retorna 500 INTERNAL_SERVER_ERROR. Todos os códigos enumerados nesta página estão registrados em Erros, e cada campo snowflake é a forma de string decimal definida por Snowflakes.

Quando o SSO está ativado e forçado, cada operação de autenticação local retorna 403 SSO_REQUIRED. A rota de status de SSO, início e conclusão de SSO, logout, ambas as rotas de sessão e todas as rotas de handoff permanecem disponíveis sob imposição. Todas as outras rotas nesta página são operações de autenticação local.

A imposição de SSO precede todas as outras verificações

Uma instância com imposição retorna 403 SSO_REQUIRED mesmo para uma solicitação de autenticação local malformada ou não autenticada.

Um login bem-sucedido cria uma sessão de autenticação e emite seu token. O Decoding Chat não define limite para sessões ativas e não remove nenhuma quando uma sessão adicional é iniciada, então uma conta mantém uma sessão por login até revogá-las através de encerrar sessões de autenticação.

A revogação de uma sessão, seja a conta a revogando ou um administrador a encerrando, impede que seu token autentique solicitações. Sua conexão Gateway principal recebe Sessão Inválida com d: false e permanece aberta, não autenticada. Nenhum Dispatch do Gateway é emitido para a própria revogação, então um cliente descobre sobre isso através desse frame ou da próxima solicitação que não consegue autenticar.

Objeto de resposta de token de autenticação

Um token de sessão recém-emitido e a conta a que pertence. Login com senha sem segundo fator, conclusão de MFA, autenticação WebAuthn detectável, registro imediato, redefinição de senha, reversão de e-mail, conclusão de SSO, pesquisa de autorização de IP e pesquisa de handoff retornam esses campos.

Estrutura

Campo	Tipo	Descrição
token1	string	O token da sessão do usuário recém-emitido
user_id	snowflake	O ID do usuário autenticado
user	objeto usuário parcial	A representação pública da conta autenticada

¹ O token é o prefixo literal flx_ seguido por exatamente 36 caracteres base62, e essa resposta é a única maneira de lê-lo

Um token de sessão é retornado uma vez

Um token de sessão perdido não pode ser recuperado por meio de nenhuma operação. A conta DEVE se autenticar novamente para obter uma nova sessão.

O resultado bem-sucedido não possui discriminador

Login por senha, registro e redefinição de senha retornam este objeto ou uma forma alternativa. A forma bem-sucedida não possui um membro próprio mfa ou registration_pending_approval, então um cliente DEVE ramificar na presença de token.

Objeto de status de SSO

O estado público do single sign-on. O mesmo objeto é incorporado pelo documento de descoberta de instância.

Estrutura

Campo	Tipo	Descrição
enabled1	boolean	Se o SSO pode ser iniciado nesta instância
enforced2	boolean	Se o SSO é obrigatório para todos os usuários
display_name	?string	O nome de exibição do provedor configurado, ou nulo quando nenhum está definido
redirect_uri	string	O URI de redirecionamento OAuth2 padrão usado para o retorno de chamada do provedor

¹ O valor é verdadeiro apenas quando o operador ativou o SSO e o provedor tem uma URL de autorização, uma URL de token, um ID de cliente e uma URL JWKS ou URL de informações do usuário. Cada URL é configurada ou descoberta a partir do emissor. Um provedor que não possui qualquer um deles relata falso

² O valor é verdadeiro apenas quando enabled também é verdadeiro, e cada operação de autenticação local então retorna 403 SSO_REQUIRED

Objeto de início de SSO

Os parâmetros para enviar o usuário ao provedor de identidade, vinculados a um novo estado de SSO.

Estrutura

Campo	Tipo	Descrição
authorization_url	string	A URL de autorização do provedor com o estado, nonce e desafio PKCE
state1	string	O estado CSRF de uso único
redirect_uri	string	O URI de retorno de chamada vinculado a este estado

¹ A primeira solicitação de concluir SSO que apresenta o estado não expirado o consome, quer essa solicitação seja bem-sucedida ou não

Um cliente DEVE retornar o estado inalterado e NÃO DEVE interpretar seu conteúdo.

Objeto de resposta de conclusão de SSO

A conclusão de SSO sempre emite uma sessão. Ele estende a resposta do token de autenticação com o redirecionamento vinculado ao estado consumido.

Estrutura

Campo	Tipo	Descrição
token	string	O token da sessão do usuário recém-emitido
user_id	snowflake	O ID do usuário autenticado
user	objeto usuário parcial	A representação pública da conta autenticada
redirect_to1	string	O redirecionamento higienizado que estava vinculado ao estado de SSO consumido

¹ O valor é a string vazia quando o início de SSO não recebeu nenhum redirect_to ou quando o valor fornecido não sobreviveu à higienização

A conclusão de SSO nunca emite um desafio MFA

A conclusão não verifica o segundo fator da conta e não pode retornar uma resposta de desafio MFA. Um cliente NÃO DEVE ramificar em um membro mfa aqui.

Objeto de resposta de registro com aprovação pendente

O ID de um registro que um administrador ainda precisa aprovar. O registro retorna este objeto quando a conta entra em aprovação.

Estrutura

Campo	Tipo	Descrição
registration_pending_approval	boolean	Sempre true
user_id	snowflake	O ID da conta registrada aguardando aprovação

Objeto de usuário parcial

Todo resultado autenticado nesta página incorpora a representação da conta pública. O objeto de usuário parcial no recurso de Usuários o define, juntamente com suas preferências de menção de resposta.

Objeto de resposta de desafio MFA

O ticket e a lista de métodos que um cliente precisa para concluir um login com um segundo fator. O login por senha retorna esse objeto quando a conta tem um.

Estrutura

Campo	Tipo	Descrição
mfa	boolean	Sempre true
ticket1	string	O ticket consumido por uma conclusão de MFA TOTP ou WebAuthn
allowed_methods2	array[string]	Os métodos disponíveis para esta conta, retirados de totp e webauthn (máx. 10 itens)
totp	boolean	Se a conta possui o tipo de autenticador de senha de uso único baseado em tempo
webauthn	boolean	Se pelo menos uma credencial WebAuthn está registrada

¹ O ticket é retido por cinco minutos, é destruído após cinco tentativas de código com falha e é consumido pela conclusão que emite a sessão

² A matriz lista os autenticadores da conta na ordem fixa totp e depois webauthn, e omite qualquer valor que a conta não possui

A conclusão TOTP aceita um código de backup não consumido

Não há rota de conclusão de código de backup e backup_code nunca aparece em allowed_methods. Concluir login com TOTP o lê a partir de code, e apenas enquanto a conta possui o tipo de autenticador TOTP. O Decoding Chat nunca relata se resta algum.

Objeto de opções de autenticação WebAuthn

Ambas as operações de opção WebAuthn retornam um objeto PublicKeyCredential request options que um navegador passa diretamente para sua solicitação de credencial. O objeto de opções de autenticação WebAuthn no recurso de Autenticação multifator define seus campos, juntamente com seu descritor de credencial WebAuthn e os objetos resultados da extensão do cliente WebAuthn.

Um desafio emitido para conclusão de MFA também está vinculado ao seu ticket e à conta, portanto não pode ser repetido em login detectável. A rota MFA lista todas as credenciais registradas para a conta resolvida em allowCredentials. A rota detectável omite o membro, pois a descoberta acontece no autenticador.

Objeto de asserção WebAuthn

Uma solicitação de autenticação WebAuthn tem o resultado da credencial do navegador como response e o desafio original do servidor como challenge. O Decoding Chat aceita campos WebAuthn adicionais. O objeto de asserção WebAuthn no recurso de Autenticação multifator define os campos, juntamente com sua resposta de asserção WebAuthn e os objetos resultados da extensão do cliente WebAuthn.

Objeto de sessão de autenticação

Uma sessão ativa pertencente à conta autenticada. A listagem é ordenada pela atividade recente aproximada, do mais novo para o mais antigo.

Estrutura

Campo	Tipo	Descrição
id_hash1	string	O resumo SHA-256 base64url do token da sessão
client_info?	objeto ?informações do cliente	Os metadados do cliente analisados, gravados quando a sessão foi criada
masked_ip	?string	O endereço IP semirredigido gravado para a sessão
approx_last_used_at?	?ISO8601 timestamp	O tempo aproximado da última solicitação que usou esta sessão
current2	boolean	Se esta sessão forneceu a credencial para a solicitação atual

¹ Este resumo é o único identificador de sessão que a API expõe e é o valor exato aceito por encerrar sessões de autenticação

² Exatamente uma entrada é verdadeira, a sessão cujo token autenticou a solicitação

Um cliente que precisa identificar sua própria sessão lê a entrada cujo current é verdadeiro.

Objeto de informações do cliente

Os metadados do dispositivo analisados registrados para uma sessão ou um handoff pendente.

Estrutura

Campo	Tipo	Descrição
platform?	?string	A plataforma do cliente gravada, resolvida do User-Agent
os?	?string	O sistema operacional gravado
browser?1	?string	O navegador gravado
device	string	A classe do dispositivo, seja mobile ou desktop
location?	objeto ?localização do cliente	A geolocalização aproximada derivada do endereço IP gravado

¹ Um cliente nativo ou Electron relata nulo, assim como uma sessão criada por uma solicitação não analisável. Um handoff omite o membro inteiramente

Os metadados do dispositivo são inferidos a partir dos cabeçalhos de solicitação do cliente. Trate platform como um rótulo de exibição, não como um identificador de aplicativo estável. A localização é aproximada e pode estar indisponível. Uma sessão então relata um location nulo, enquanto um handoff relata um objeto com membros nulos.

Objeto de localização do cliente

A geolocalização aproximada que o Decoding Chat deriva do endereço IP gravado para uma sessão ou handoff.

Estrutura

Campo	Tipo	Descrição
city?	?string	A cidade aproximada
region?	?string	A região aproximada
country?	?string	O país aproximado

Objeto de validade de redefinição de senha

O resultado da verificação de um token de redefinição de senha sem consumi-lo.

Estrutura

Campo	Tipo	Descrição
valid1	boolean	Se o token é válido e não expirado

¹ Um token de redefinição de senha expira uma hora após ser emitido

Objeto de pesquisa de autorização por IP

O estado de um ticket de autorização por IP, conforme observado pelo dispositivo cujo login estava retido.

Estrutura

Campo	Tipo	Descrição
completed	boolean	Se o link de autorização foi usado e uma sessão foi emitida
token?1	?string	O token da sessão do usuário recém-emitido
user_id?1	?snowflake	O ID do usuário autenticado
user?1	objeto ?usuário parcial	A representação pública da conta autenticada

¹ Os campos estão presentes juntos apenas quando completed é verdadeiro, e um ticket ainda pendente retorna completed sozinho

Objeto de sugestões de nome de usuário

Candidatos a nome de usuário derivados de um nome de exibição.

Estrutura

Campo	Tipo	Descrição
suggestions1	array[string]	Os candidatos a nome de usuário gerados (máx. 20 itens)

¹ A matriz tem no máximo um candidato. Está vazia quando o nome de exibição fornecido não deriva em nenhum nome de usuário permitido

Objeto de iniciação de handoff

O código que identifica um handoff de desktop pendente.

Estrutura

Campo	Tipo	Descrição
code1	string	O código de handoff a apresentar ao dispositivo aprovador
expires_at	ISO8601 timestamp	O horário em que o handoff expira, cinco minutos após a criação
poll_secret?	string	O segredo que o dispositivo iniciador apresenta para ler o token emitido

¹ O código tem 12 caracteres retirados do alfabeto ABCDEFGHJKMNPQRSTUVWXYZ23456789, renderizados como dois grupos de seis separados por um hífen

Apenas o código lê os metadados do dispositivo

Qualquer pessoa que descobre o código lê os metadados do dispositivo pendente. Ler o token e cancelar o handoff requerem poll_secret. Um cliente DEVE mostrar o código apenas à pessoa que executa o handoff.

Objeto de informações de handoff

Os metadados do dispositivo exibidos para o dispositivo aprovador antes de transferir uma sessão.

Estrutura

Campo	Tipo	Descrição
status	string	O estado, seja pending ou expired
client_info?1	objeto ?informações do cliente	Os metadados do dispositivo iniciador

¹ O valor é nulo sempre que o status for expired

Objeto de status de handoff

O estado de um handoff para desktop conforme observado pelo dispositivo que o iniciou.

Estrutura

Campo	Tipo	Descrição
status1	string	O estado, um de pending, expired ou completed
token?2	?string	O token da sessão do usuário recém-emitido
user_id?2	?snowflake	O ID do usuário autenticado
user?2	objeto ?usuário parcial	A representação pública da conta autenticada

¹ Um código desconhecido e um código expirado ambos relatam expired

² Os campos estão presentes juntos apenas quando o status é completed

Obter status de SSO

GET/v1/auth/sso/statusUnauthenticated

Lê o estado público do single sign-on da instância. Autenticação não é necessária. Retorna um objeto status de SSO.

A operação permanece disponível enquanto o SSO é imposto. Compartilha o bucket auth:sso:start, que permite 10 solicitações a cada 10 segundos.

Resposta

Status	Corpo	Condição
200	objeto status de SSO	O estado público do SSO foi lido
429	resposta de limite de taxa	A rota ou o bucket global nega a solicitação
500	resposta de erro	Ocorre uma falha interna inesperada
503	resposta de erro	A instância está em seu limite máximo de solicitações em andamento

Iniciar SSO

POST/v1/auth/sso/startUnauthenticated

Inicia um fluxo de single sign-on. Autenticação não é necessária. Retorna um objeto início de SSO. Envie o usuário para authorization_url inalterado.

Corpo JSON

Campo	Tipo	Descrição
redirect_to?1	?string	O redirecionamento pós-autenticação para vincular ao estado
redirect_uri?2	?string	O URI de retorno de chamada do provedor a ser usado em vez do padrão configurado

¹ O Decoding Chat higieniza o valor antes de vinculá-lo ao estado e descarta um valor que não sobrevive, o que a resposta de conclusão de SSO relata como a string vazia. A higienização mantém o valor aparado apenas quando ele começa com um único /, tem no máximo 2.048 caracteres e não contém retorno de carro (CR) ou alimentação de linha (LF)

² Os valores aceitos são o padrão da instância relatado como redirect_uri por obter status de SSO e o retorno de chamada móvel fluxer://auth/sso/callback, e qualquer outro valor retorna o código de campo INVALID_URL_FORMAT. O valor aceito é vinculado ao estado e reutilizado na troca de token

Resposta

Status	Corpo	Condição
200	objeto início de SSO	O estado foi criado
400	resposta de erro	O corpo é malformado ou o URI de retorno de chamada não é um valor aceito
403	resposta de erro	O SSO está desativado ou sua configuração resolvida está incompleta, retornando FEATURE_TEMPORARILY_DISABLED
429	resposta de limite de taxa	A rota ou o bucket global nega a solicitação
500	resposta de erro	Ocorre uma falha interna inesperada
503	resposta de erro	A instância está em seu limite máximo de solicitações em andamento

Efeitos colaterais

O estado retornado pode ser concluído uma vez e expira após dez minutos. O início do fluxo não altera nenhum estado da conta e não emite Dispatch do Gateway.

Limite de taxa

10 solicitações por 10 segundos, no bucket auth:sso:start.

Concluir SSO

POST/v1/auth/sso/completeUnauthenticated

Conclui um fluxo de single sign-on e entra ou cria a conta vinculada. Autenticação não é necessária. Retorna uma resposta de conclusão de SSO.

Corpo JSON

Campo	Tipo	Descrição
code	string	O código de autorização retornado pelo provedor (1-4096 caracteres)
state1	string	O estado retornado pelo início de SSO (1-4096 caracteres)

¹ O estado é consumido na primeira chamada que o resolve, portanto uma solicitação repetida com o mesmo estado retorna o código de campo INVALID_OR_EXPIRED_SSO_STATE

A vinculação de identidade é de um para um

Um sujeito provedor está vinculado a exatamente uma conta do Decoding Chat, e uma conta aceita exatamente um sujeito provedor. Um sujeito já vinculado a uma conta diferente, ou um novo sujeito para uma conta que já possui um sujeito vinculado diferente, retorna o código de campo SSO_IDENTITY_MISMATCH.

Um e-mail de provedor verificado adota uma conta local

Quando o sujeito ainda não está vinculado, o Decoding Chat adota qualquer conta existente que contenha o endereço de e-mail verificado na reivindicação do provedor e vincula o sujeito a ela, tenha ou não essa conta uma senha ou um autenticador. Um provedor que atesta um endereço verificado arbitrário, portanto, assume o controle da conta local correspondente. Um operador DEVE habilitar o SSO apenas para um provedor que controla os endereços que ele atesta.

O Decoding Chat recusa a adoção apenas quando a conta já possui um sujeito provedor diferente.

A troca do provedor e a resolução de reivindicações podem retornar os códigos de campo INVALID_SSO_AUTHORIZATION_CODE, INVALID_SSO_TOKEN, FAILED_TO_FETCH_SSO_USER_INFO, FAILED_TO_PARSE_SSO_USER_INFO, SSO_PROVIDER_DID_NOT_RETURN_EMAIL, SSO_IDENTITY_MISMATCH, SSO_MISCONFIGURED, INVALID_EMAIL_ADDRESS, EMAIL_DOMAIN_NOT_ALLOWED_FOR_SSO ou SSO_UNABLE_TO_ALLOCATE_DISCRIMINATOR. Um e-mail de provedor não verificado usa o código de campo INVALID_SSO_TOKEN.

O registro fechado retorna 403 REGISTRATION_CLOSED, uma conta desconhecida em uma instância com o provisionamento automático desativado retorna 403 SSO_REQUIRED, uma conta aguardando aprovação retorna 403 REGISTRATION_PENDING_APPROVAL, e a suspensão da conta retorna 403 ACCOUNT_SUSPENDED_TEMPORARILY ou 403 ACCOUNT_SUSPENDED_PERMANENTLY. Um nome de usuário provisionado ou nome de exibição contendo uma substring bloqueada retorna 403 CONTENT_BLOCKED.

Um e-mail de provedor verificado que adota uma conta de bot retorna 403 BOT_USER_AUTH_SESSION_CREATION_DENIED, e um que adota um registro rejeitado retorna 403 REGISTRATION_REJECTED.

Resposta

Status	Corpo	Condição
200	resposta de conclusão de SSO	SSO concluído e uma sessão foi emitida
400	resposta de erro	O corpo, o estado, a troca do provedor, as reivindicações ou o e-mail resolvido é inválido
403	resposta de erro	SSO, política de registro, uma conta de bot ou suspensão de conta rejeita a conclusão
429	resposta de limite de taxa	A rota ou o bucket global nega a solicitação
500	resposta de erro	A troca do provedor de identidade não pôde ser concluída
503	resposta de erro	A instância está em seu limite máximo de solicitações em andamento

Efeitos colaterais

Uma conclusão com falha requer um novo fluxo de SSO. Uma conta recém-criada tem um e-mail verificado, sem senha local ou autenticador, e configurações padrão. O registro via SSO não aceita convites e não entra em nenhuma guilda.

O registro em modo de aprovação, em vez disso, retorna 403 REGISTRATION_PENDING_APPROVAL e não cria nenhuma sessão. Caso contrário, a operação cria uma sessão de autenticação e limpa uma suspensão temporária expirada.

Limite de taxa

15 solicitações por 10 segundos, no bucket auth:sso:complete.

Registrar uma conta

POST/v1/auth/registerUnauthenticated

Cria uma conta comum. Retorna uma resposta de token de autenticação quando a instância admite a conta imediatamente e uma resposta de registro com aprovação pendente quando não o faz. Emite um evento de Gateway Guild Member Add para cada guilda em que a nova conta entra por meio de um convite ou por meio da única guilda de comunidade da instância.

O registro verifica o CAPTCHA quando o CAPTCHA está ativado. Ele permite 3 tentativas por hora para cada endereço IP de cliente e 15 por hora para cada sub-rede de cliente, que é a rede IPv4 /24 ou IPv6 /48. Um endereço de e-mail fornecido permite 3 tentativas a cada 15 minutos por conta própria. Essas permissões são separadas do bucket da rota, e apenas uma implantação com dev.relax_registration_rate_limits definido como verdadeiro as desativa.

Cabeçalhos da solicitação

Campo	Tipo	Descrição
X-Captcha-Token?1	string	A prova emitida pelo provedor de CAPTCHA
X-Captcha-Type?2	string	O provedor que emitiu a prova, seja hcaptcha ou turnstile
Accept-Language?3	string	A etiqueta de idioma que seleciona o local armazenado na nova conta

¹ Uma prova ausente retorna 400 CAPTCHA_REQUIRED e uma prova rejeitada retorna 400 INVALID_CAPTCHA, e a verificação é ignorada inteiramente quando o CAPTCHA está desativado para a instância

² Omitir o cabeçalho seleciona o provedor configurado da instância

³ O local analisado se torna o local da conta e seleciona o idioma do e-mail de verificação

Corpo JSON

Campo	Tipo	Descrição
email?1	string	O endereço de e-mail da conta
username?2	string	O nome de usuário da conta (1-32 caracteres, letras, dígitos e sublinhados)
global_name?	string	O nome de exibição após a normalização (1-32 caracteres)
password?3	string	A senha da conta (8-256 caracteres)
date_of_birth?4	string	A data de nascimento na forma exata YYYY-MM-DD
consent?5	boolean	Se os termos de serviço e a política de privacidade são aceitos (padrão falso)
invite_code?	?string	O convite aceito imediatamente após o registro (0-256 caracteres)
registration_url_code?6	?string	O código de URL de registro emitido pelo administrador (1-256 caracteres)
theme?	string	A preferência de tema inicial, um de dark, dark_legacy, coal, light ou system

¹ Omitir o endereço de e-mail cria uma conta não reivindicada, que não tem caminho de recuperação até ser reivindicada. Um endereço cujo domínio não tem registros DNS utilizáveis, ou cujo domínio de nível superior é bloqueado pela política da conta, retorna o código de campo INVALID_EMAIL_ADDRESS, e um endereço já em uso retorna EMAIL_ALREADY_IN_USE

² Omitir o nome de usuário deriva um de global_name quando esse valor produz um nome de usuário permitido e, caso contrário, aloca um nome de usuário gerado, em ambos os casos com um discriminador alocado pelo servidor

³ A senha é verificada em relação ao corpus público de senhas vazadas descrito em redefinir uma senha, e uma correspondência retorna o código de campo PASSWORD_IS_TOO_COMMON

⁴ O campo é obrigatório quando a instância coleta data de nascimento. Um valor ausente ou em branco, ou um valor no formato YYYY-MM-DD que não seja uma data de calendário real, retorna o código de campo INVALID_DATE_OF_BIRTH_FORMAT. Um valor que não tem dez caracteres no formato YYYY-MM-DD falha na validação do esquema com o código de campo STRING_LENGTH_EXACT ou INVALID_FORMAT

⁵ Um valor falso ou ausente retorna o código de campo MUST_AGREE_TO_TOS_AND_PRIVACY_POLICY na instância oficial e em qualquer instância que publique um documento de termos ou privacidade

⁶ Um código fornecido em uma instância com URLs de registro de administrador desativadas e um código que não é resolvido, ambos retornam 400 REGISTRATION_URL_INVALID. Um código válido substitui o modo de registro fechado e substitui o modo de aprovação da instância por sua própria configuração de aprovação

O Decoding Chat resolve a região a partir do endereço IP do cliente, e uma idade abaixo do mínimo para essa região retorna o código de campo MUST_BE_MINIMUM_AGE. Esse mínimo é de 13 anos, a menos que a política da conta defina um mínimo diferente para a região, e o mínimo aplicado aparece apenas na mensagem localizada.

O registro retorna 403 REGISTRATION_CLOSED quando a instância é fechada e nenhuma URL de registro válida foi fornecida. Um nome de usuário cujo espaço discriminador está esgotado retorna o código de campo TOO_MANY_USERS_WITH_THIS_USERNAME. Um nome de usuário ou nome de exibição contendo uma substring bloqueada retorna 403 CONTENT_BLOCKED.

O registro informa um endereço já em uso

Fazer login com uma senha e solicitar recuperação de senha são seguros para enumeração, e o registro não é. Um endereço que já possui uma conta retorna o código de campo EMAIL_ALREADY_IN_USE, portanto um chamador não autenticado aprende com a resposta se esse endereço está registrado.

O registro não é idempotente

Não há chave de repetição. Uma solicitação repetida com os mesmos valores cria uma segunda conta ou falha no endereço de e-mail duplicado quando um é fornecido. Um cliente que perde a resposta DEVE resolver o resultado tentando fazer login.

Resposta

Status	Corpo	Condição
200	resposta de token de autenticação | resposta de registro com aprovação pendente	O registro foi concluído ou entrou no estado de aprovação
400	resposta de erro	O corpo, CAPTCHA, campos da conta ou código da URL de registro é inválido
403	resposta de erro	A imposição de SSO, a política de registro ou a moderação de conteúdo rejeita o registro
429	resposta de limite de taxa	Um bucket de rota, global, e-mail, IP ou sub-rede nega a solicitação
500	resposta de erro	Ocorre uma falha interna inesperada
503	resposta de erro	A instância está em seu limite máximo de solicitações em andamento

Efeitos colaterais

A operação aplica as políticas de registro, domínio de e-mail, senha vazada e região da instância antes de criar a conta, e sua política de risco pode definir sinalizadores de atividade suspeita na conta criada. Ele registra os termos aceitos e a política de privacidade, autoriza o endereço IP do cliente de registro e envia uma mensagem de verificação de e-mail quando a instância envia e-mail. Uma instância que não envia e-mail marca o endereço verificado na criação.

O registro aceita o invite_code do corpo, ou o convite de auto-join configurado da instância quando o corpo não tem nenhum. Em uma instância com o modo de comunidade única habilitado, a conta também entra na guilda da comunidade. Cada entrada emite Guild Member Add para as sessões da guilda afetada. A política de registro pode suprimir a admissão do convite.

O registro em modo de aprovação não cria participação na guilda nem sessão de autenticação, e a conta não pode fazer login até que um administrador a aprove. Qualquer outro registro bem-sucedido cria uma sessão e retorna seu token.

Limite de taxa

10 solicitações por 10 segundos, no bucket auth:register.

Fazer login com uma senha

POST/v1/auth/loginUnauthenticated

Valida e-mail local e credenciais de senha. Autenticação não é necessária. Retorna uma resposta de token de autenticação quando não há segundo fator nem aprovação de IP pendente e uma resposta de desafio MFA quando a conta possui um segundo fator.

O login verifica o CAPTCHA quando o CAPTCHA está ativado. Também permite 10 tentativas por endereço IP do cliente em 30 minutos, chaveadas pelo endereço IPv4 exato ou pela rede IPv6 /64, e 5 tentativas por endereço de e-mail em 15 minutos. Toda tentativa admitida consome ambas as permissões, independentemente de as credenciais se revelarem corretas, e um login bem-sucedido não limpa nenhuma.

Cabeçalhos da solicitação

Campo	Tipo	Descrição
X-Captcha-Token?1	string	A prova emitida pelo provedor de CAPTCHA
X-Captcha-Type?2	string	O provedor que emitiu a prova, seja hcaptcha ou turnstile
X-Fluxer-Client-Properties?3	string	O JSON codificado em base64 com o os do cliente que está relatando
User-Agent?3	string	A string do cliente gravada na sessão criada e mostrada por listar sessões de autenticação

¹ Uma prova ausente retorna 400 CAPTCHA_REQUIRED e uma prova rejeitada retorna 400 INVALID_CAPTCHA, e a verificação é ignorada inteiramente quando o CAPTCHA está desativado para a instância

² Omitir o cabeçalho seleciona o provedor configurado da instância

³ Ambos os valores alimentam o objeto informações do cliente registrado na sessão, e X-Fluxer-Client-Properties é lido apenas para um User-Agent nativo do Decoding Chat

Corpo JSON

Campo	Tipo	Descrição
email	string	O endereço de e-mail da conta
password	string	A senha da conta (8-256 caracteres)
invite_code?1	?string	O convite aceito imediatamente após um login bem-sucedido (0-256 caracteres)

¹ O convite é aceito apenas em um login que é concluído sem um segundo fator, e a falha em aceitá-lo não falha no login. Um login retido para autorização de IP descarta o convite

Contas desconhecidas e senhas incorretas são indistinguíveis

Um endereço de e-mail desconhecido e uma senha incorreta retornam os mesmos códigos de campo emparelhados INVALID_EMAIL_OR_PASSWORD em email e password.

Um novo endereço IP do cliente em uma conta que não possui nem um segundo fator nem o sinalizador de revisor da app store retorna 403 IP_AUTHORIZATION_REQUIRED. O corpo desse erro tem ip_authorization_required definido como verdadeiro, o ticket usado pelas operações de autorização de IP, o email da conta e resend_available_in definido para 30 segundos.

Quando a instância desativou a autorização de novo IP ou não envia e-mail, o Decoding Chat autoriza o endereço IP do cliente silenciosamente e o login continua. Uma conta que já possui um segundo fator nunca entra na autorização de IP.

A política da conta pode retornar 403 REGISTRATION_PENDING_APPROVAL, 403 REGISTRATION_REJECTED, 403 ACCOUNT_SUSPENDED_TEMPORARILY ou 403 ACCOUNT_SUSPENDED_PERMANENTLY. Uma conta de bot retorna 403 BOT_USER_AUTH_ENDPOINT_ACCESS_DENIED.

Uma senha verificada reativa a conta

Em uma conta que o usuário desativou, uma senha correta limpa o estado desativado. Ela também cancela uma exclusão agendada pelo próprio se a exclusão não tiver sido iniciada. Ambos acontecem antes que qualquer segundo fator seja solicitado, sem uma etapa de confirmação separada. Quando o apagamento começa, o login retorna ACCOUNT_SUSPENDED_PERMANENTLY.

Uma senha correta também limpa uma suspensão temporária expirada antes de qualquer segundo fator ser solicitado. Uma suspensão de administrador temporária ou permanente ativa permanece em vigor, e o login retorna seu 403.

Resposta

Status	Corpo	Condição
200	resposta de token de autenticação | resposta de desafio MFA	As credenciais são aceitas
400	resposta de erro	O corpo, CAPTCHA, e-mail ou senha é inválido
403	resposta de erro	A política de conta, a imposição de SSO ou a autorização de IP impedem o login
409	resposta de erro	CONFLICT, porque o estado de exclusão foi alterado ao cancelar uma exclusão auto-agendada
429	resposta de limite de taxa	Um bucket de rota, global, e-mail ou IP nega a solicitação
500	resposta de erro	Ocorre uma falha interna inesperada
503	resposta de erro	A instância está em seu limite máximo de solicitações em andamento

Efeitos colaterais

Um login bem-sucedido em uma conta com um segundo fator retorna um ticket MFA válido por cinco minutos e não emite sessão. Quando a aprovação de IP é necessária, o ticket de autorização permanece válido por 15 minutos e a conta recebe uma mensagem de autorização.

Um login bem-sucedido sem aprovação de MFA ou IP pendente cria uma sessão de autenticação. Ele aceita o convite fornecido primeiro, o que emite Guild Member Add para as sessões da guilda.

Limite de taxa

10 solicitações por 10 segundos, no bucket auth:login.

Concluir o login com TOTP

POST/v1/auth/login/mfa/totpUnauthenticated

Consome um ticket MFA e valida uma senha de uso único baseada em tempo ou um código de backup não consumido e cria a sessão. Autenticação não é necessária. Retorna uma resposta de token de autenticação.

A verificação MFA também permite 10 tentativas com falha por conta em 15 minutos e destrói o ticket após 5 tentativas com falha.

Corpo JSON

Campo	Tipo	Descrição
code1	string	O código do autenticador ou um código de backup não consumido
ticket	string	O ticket retornado pelo login com senha

¹ Um código autenticador validado é reivindicado por 30 segundos, portanto, o mesmo código não pode ser apresentado duas vezes. Um código de backup é consumido permanentemente na tentativa que o aceita

Um ticket expirado ou desconhecido retorna o código de campo SESSION_TIMEOUT em ticket. Uma conta sem inscrição TOTP retorna o código de campo TOTP_NOT_ENABLED em code. Tanto um código incorreto quanto qualquer código apresentado após a permissão de tentativa por conta ou por ticket estar esgotada retornam o código de campo INVALID_CODE em code. Um ticket que é resolvido para uma conta de bot retorna 403 BOT_USER_AUTH_ENDPOINT_ACCESS_DENIED.

Resposta

Status	Corpo	Condição
200	resposta de token de autenticação	O ticket e o código são aceitos
400	resposta de erro	O corpo, ticket ou código é inválido
403	resposta de erro	A imposição de SSO rejeita a operação ou o ticket se resolve em uma conta de bot
404	resposta de erro	O ticket se resolve para uma conta que não existe mais
429	resposta de limite de taxa	A rota ou o bucket global nega a solicitação
500	resposta de erro	Ocorre uma falha interna inesperada
503	resposta de erro	A instância está em seu limite máximo de solicitações em andamento

Efeitos colaterais

O sucesso consome o ticket, limpa os contadores de tentativa com falha por conta e por ticket e cria uma sessão de autenticação. Uma falha consome uma tentativa de cada contador. Nenhum Dispatch do Gateway é emitido.

Limite de taxa

5 solicitações por minuto, no bucket compartilhado auth:login:mfa.

Obter opções MFA do WebAuthn

POST/v1/auth/login/mfa/webauthn/authentication-optionsUnauthenticated

Resolve a conta a partir de um ticket MFA e cria um desafio restrito às credenciais registradas daquela conta. Autenticação não é necessária. Retorna um objeto opções de autenticação WebAuthn.

Corpo JSON

Campo	Tipo	Descrição
ticket1	string	O ticket retornado pelo login com senha (1-256 caracteres)

¹ O ticket é lido, mas não consumido

Um cliente DEVE ainda concluir o desafio retornado através de concluir o login com WebAuthn MFA antes que o ticket expire. Um ticket expirado ou desconhecido retorna o código de campo SESSION_TIMEOUT em ticket. Uma conta sem nenhuma credencial registrada retorna 400 NO_PASSKEYS_REGISTERED.

Resposta

Status	Corpo	Condição
200	objeto opções de autenticação WebAuthn	O ticket se resolve em uma conta com pelo menos uma credencial
400	resposta de erro	O corpo ou ticket é inválido, ou a conta não possui credencial registrada
403	resposta de erro	A imposição de SSO rejeita a operação
429	resposta de limite de taxa	A rota ou o bucket global nega a solicitação
500	resposta de erro	Ocorre uma falha interna inesperada
503	resposta de erro	A instância está em seu limite máximo de solicitações em andamento

Efeitos colaterais

A operação emite um desafio WebAuthn de uso único válido por cinco minutos e vinculado a esse fluxo MFA, conta e ticket. Ela não altera o estado da conta. Nenhum Dispatch do Gateway é emitido.

Limite de taxa

5 solicitações por minuto, no bucket compartilhado auth:login:mfa.

Concluir o login com WebAuthn MFA

POST/v1/auth/login/mfa/webauthnUnauthenticated

Consome o ticket MFA, verifica a asserção WebAuthn contra o desafio e cria a sessão. Autenticação não é necessária. Retorna uma resposta de token de autenticação.

Corpo JSON

Campo	Tipo	Descrição
response	objeto asserção WebAuthn	A asserção da credencial do navegador
challenge1	string	O desafio retornado por obter opções MFA do WebAuthn
ticket	string	O ticket retornado pelo login com senha

¹ O desafio é consumido antes da verificação e é aceito apenas quando seu contexto vinculado, conta e ticket correspondem todos a esta solicitação

Um ticket expirado ou desconhecido retorna o código de campo SESSION_TIMEOUT em ticket. Uma incompatibilidade de desafio, uma credencial desconhecida, uma chave pública armazenada que não pode ser decodificada, um contador de assinaturas que o autenticador não avançou e uma falha na verificação de assinatura retornam 401 PASSKEY_AUTHENTICATION_FAILED. Uma asserção verificada cujo contador de assinaturas reportado não pode ser lido retorna 500 INVALID_WEBAUTHN_AUTHENTICATION_COUNTER.

Esta operação compartilha as permissões de tentativa MFA de concluir o login com TOTP. Ele permite 10 tentativas com falha por conta em 15 minutos e destrói o ticket após 5 tentativas com falha. Uma permissão esgotada retorna o código de campo INVALID_CODE em ticket.

Resposta

Status	Corpo	Condição
200	resposta de token de autenticação	O ticket e a asserção são aceitos
400	resposta de erro	O corpo ou ticket é inválido
401	resposta de erro	Falha na verificação do desafio ou da asserção
403	resposta de erro	A imposição de SSO rejeita a operação ou o ticket resolve para uma conta de bot
404	resposta de erro	O ticket se resolve para uma conta que não existe mais
429	resposta de limite de taxa	A rota ou o bucket global nega a solicitação
500	resposta de erro	A asserção verificada não relatou nenhum contador de assinaturas legível, ou a solicitação não pôde ser concluída
503	resposta de erro	A instância está em seu limite máximo de solicitações em andamento

Efeitos colaterais

O sucesso consome o desafio e o ticket e cria uma sessão de autenticação. Nenhum Dispatch do Gateway é emitido.

Limite de taxa

5 solicitações por minuto, no bucket compartilhado auth:login:mfa.

Obter opções WebAuthn detectáveis

POST/v1/auth/webauthn/authentication-optionsUnauthenticated

Cria um desafio para login detectável. Autenticação não é necessária. Retorna um objeto opções de autenticação WebAuthn.

A solicitação não tem corpo e não usa parâmetros. Ele não restringe as credenciais em allowCredentials porque a seleção ocorre no autenticador.

Resposta

Status	Corpo	Condição
200	objeto opções de autenticação WebAuthn	O desafio detectável foi emitido
403	resposta de erro	A imposição de SSO rejeita a operação
429	resposta de limite de taxa	A rota ou o bucket global nega a solicitação
500	resposta de erro	Ocorre uma falha interna inesperada
503	resposta de erro	A instância está em seu limite máximo de solicitações em andamento

Efeitos colaterais

A operação emite um desafio WebAuthn detectável de uso único válido por cinco minutos e vinculado apenas ao contexto detectável. Ela não altera o estado da conta. Nenhum Dispatch do Gateway é emitido.

Limite de taxa

20 solicitações por 10 segundos, no bucket auth:webauthn:options.

Autenticar com WebAuthn

POST/v1/auth/webauthn/authenticateUnauthenticated

Resolve a conta a partir do ID da credencial apresentado, verifica a asserção com verificação de usuário necessária, aplica a política de suspensão de conta e cria a sessão. Autenticação não é necessária. Retorna uma resposta de token de autenticação.

Corpo JSON

Campo	Tipo	Descrição
response	objeto asserção WebAuthn	A asserção da credencial do navegador
challenge1	string	O desafio retornado por obter opções WebAuthn detectáveis

¹ O desafio é consumido antes da verificação e é aceito apenas quando foi emitido para o contexto detectável; portanto, um desafio emitido para MFA ou para modo sudo não pode ser usado aqui

Um ID de credencial desconhecido, uma incompatibilidade de desafio, uma chave pública armazenada que não pode ser decodificada, um contador de assinaturas que o autenticador não avançou e uma falha na verificação de assinatura retornam 401 PASSKEY_AUTHENTICATION_FAILED. Uma asserção verificada cujo contador de assinaturas reportado não pode ser lido retorna 500 INVALID_WEBAUTHN_AUTHENTICATION_COUNTER. A suspensão da conta retorna 403 ACCOUNT_SUSPENDED_TEMPORARILY ou 403 ACCOUNT_SUSPENDED_PERMANENTLY.

Uma conta de bot retorna 403 BOT_USER_AUTH_SESSION_CREATION_DENIED. Uma conta que não foi admitida retorna 403 REGISTRATION_PENDING_APPROVAL ou 403 REGISTRATION_REJECTED.

Resposta

Status	Corpo	Condição
200	resposta de token de autenticação	A asserção e a política da conta são aceitas
400	resposta de erro	O corpo é malformado
401	resposta de erro	Falha na verificação do desafio ou da asserção
403	resposta de erro	A imposição de SSO, a suspensão da conta, uma conta de bot ou um registro não admitido rejeita o login
429	resposta de limite de taxa	A rota ou o bucket global nega a solicitação
500	resposta de erro	A asserção verificada não relatou nenhum contador de assinaturas legível, ou a solicitação não pôde ser concluída
503	resposta de erro	A instância está em seu limite máximo de solicitações em andamento

Efeitos colaterais

O sucesso consome o desafio, limpa uma suspensão temporária expirada e cria uma sessão de autenticação. Nenhum Dispatch do Gateway é emitido.

Limite de taxa

10 solicitações por 10 segundos, no bucket auth:webauthn:authenticate.

Sair (Logout)

POST/v1/auth/logoutBot

Revoga a sessão identificada pelo token da sessão do usuário no cabeçalho Authorization. Retorna 204 sem nenhum corpo.

A solicitação não tem corpo. A operação requer uma credencial que resolva para uma conta e admite uma sinalizada por atividade suspeita. Um token ausente, malformado ou desconhecido retorna 401 UNAUTHORIZED. Um token bearer OAuth2 retorna 403 ACCESS_DENIED. Um bot não possui sessão, então um token de bot é aceito e não revoga nada.

Sair revoga exatamente a sessão chamadora

As outras sessões da conta, suas concessões OAuth2 e qualquer ticket MFA, ticket de autorização de IP ou handoff de desktop pendentes sobrevivem. Use encerrar sessões de autenticação para revogar outras sessões.

Resposta

Status	Corpo	Condição
204	vazio	A sessão foi revogada, ou a credencial é um token de bot
401	resposta de erro	O token está ausente, malformado ou não nomeia nenhuma sessão ativa
403	resposta de erro	A credencial é um token bearer OAuth2
429	resposta de limite de taxa	A rota ou o bucket global nega a solicitação
500	resposta de erro	A revogação da sessão falha inesperadamente
503	resposta de erro	A instância está em seu limite máximo de solicitações em andamento

Efeitos colaterais

A revogação desta sessão encerra sua sessão do Gateway, conforme afirma o comportamento compartilhado. Nenhum Dispatch do Gateway é emitido para a revogação.

Limite de taxa

20 solicitações por 10 segundos, no bucket auth:logout.

Verificar um endereço de e-mail

POST/v1/auth/verifyUnauthenticated

Consome um token de verificação de e-mail e marca o endereço atual da conta como verificado. Autenticação não é necessária. Retorna 204 sem nenhum corpo.

Corpo JSON

Campo	Tipo	Descrição
token	string	O token entregue por e-mail, exatamente 64 caracteres

Um token desconhecido, já consumido ou de conta excluída retorna o código de campo INVALID_OR_EXPIRED_VERIFICATION_TOKEN.

A verificação marca o endereço atual da conta

O Decoding Chat nunca compara o endereço da conta com aquele para o qual o token foi emitido. Portanto, uma conta que altera seu endereço enquanto um token de verificação está pendente pode verificar o novo endereço com o token antigo.

Resposta

Status	Corpo	Condição
204	vazio	O endereço foi verificado
400	resposta de erro	O corpo ou token é inválido
403	resposta de erro	A imposição de SSO rejeita a operação, ou o token resolve para uma conta de bot
429	resposta de limite de taxa	A rota ou o bucket global nega a solicitação
500	resposta de erro	Ocorre uma falha interna inesperada
503	resposta de erro	A instância está em seu limite máximo de solicitações em andamento

Efeitos colaterais

A operação marca o endereço atual como verificado, limpa seu estado devolvido e limpa todo sinalizador de atividade suspeita que a verificação ou reverificação de um endereço de e-mail satisfaça. Emite um Gateway Dispatch de User Update para as próprias sessões da conta.

Limite de taxa

10 solicitações por minuto, no bucket auth:verify.

Reenviar verificação de e-mail

POST/v1/auth/verify/resend

Emite e envia um novo token de verificação de e-mail para a conta autenticada. Requer um token de sessão de usuário para um usuário comum. Retorna 204 sem nenhum corpo.

A solicitação não tem corpo. Quando o endereço atual já está verificado e nenhum sinalizador de atividade suspeita de reverificação está definido, a operação retorna 204 e não envia nada.

Resposta

Status	Corpo	Condição
204	vazio	Uma mensagem foi enviada ou a verificação já foi concluída
401	resposta de erro	A credencial de sessão do usuário está ausente ou é inválida
403	resposta de erro	A imposição de SSO rejeita a operação, ou a credencial é um token de bot ou um token bearer OAuth2
429	resposta de limite de taxa	Uma rota, bucket global ou por endereço nega a solicitação
500	resposta de erro	Ocorre uma falha interna inesperada
503	resposta de erro	A instância está em seu limite máximo de solicitações em andamento

Efeitos colaterais

A operação cria um token de verificação de 64 caracteres vinculado à conta e ao seu endereço atual, válido por 24 horas, e envia a mensagem de verificação. Tokens de verificação emitidos anteriormente permanecem válidos. Nenhum Dispatch do Gateway é emitido.

Limite de taxa

10 solicitações por minuto, no bucket auth:verify:resend, e o endereço de destino permite 3 mensagens a cada 15 minutos.

Solicitar recuperação de senha

POST/v1/auth/forgotUnauthenticated

Aceita uma solicitação de recuperação de senha para um endereço de e-mail. Autenticação não é necessária. Retorna 204 sem nenhum corpo.

A recuperação de senha verifica o CAPTCHA quando o CAPTCHA está ativado. O Decoding Chat consome o endereço IP do cliente e as permissões de endereço de e-mail antes de validar o endereço, e esgotar qualquer um dos dois retorna 429.

Cabeçalhos da solicitação

Campo	Tipo	Descrição
X-Captcha-Token?1	string	A prova emitida pelo provedor de CAPTCHA
X-Captcha-Type?2	string	O provedor que emitiu a prova, seja hcaptcha ou turnstile

¹ Uma prova ausente retorna 400 CAPTCHA_REQUIRED e uma prova rejeitada retorna 400 INVALID_CAPTCHA, e a verificação é ignorada inteiramente quando o CAPTCHA está desativado para a instância

² Omitir o cabeçalho seleciona o provedor configurado da instância

Corpo JSON

Campo	Tipo	Descrição
email1	string	O endereço que recebe o link de redefinição

¹ Um endereço cujo domínio não tem registros DNS utilizáveis retorna o código de campo INVALID_EMAIL_ADDRESS, enquanto um endereço que passa na validação DNS, mas não pertence a nenhuma conta, retorna a resposta de sucesso comum

A existência da conta não é divulgada

Um endereço que se resolve para nenhuma conta produz a mesma resposta 204 que um endereço que se resolve para uma conta comum. Apenas uma falha de validação de DNS, o bucket da rota, o endereço IP do cliente e as permissões de endereço de e-mail e um endereço pertencente a uma conta de bot podem produzir um resultado diferente.

Resposta

Status	Corpo	Condição
204	vazio	A solicitação foi aceita, independentemente de a conta existir ou não
400	resposta de erro	O corpo, CAPTCHA ou endereço de e-mail é inválido
403	resposta de erro	A imposição de SSO rejeita a operação, ou o endereço pertence a uma conta de bot
429	resposta de limite de taxa	Uma rota, bucket global, e-mail ou IP de cliente nega a solicitação
500	resposta de erro	Ocorre uma falha interna inesperada
503	resposta de erro	A instância está em seu limite máximo de solicitações em andamento

Efeitos colaterais

O Decoding Chat envia um token de redefinição de 64 caracteres por e-mail para um endereço que se resolve para uma conta. O token está vinculado a essa conta e ao seu endereço atual e é válido por uma hora. Nada mais muda. Nenhum Dispatch do Gateway é emitido.

Limite de taxa

5 solicitações por minuto, no bucket auth:forgot, e a recuperação permite 20 tentativas por endereço IP de cliente e 5 tentativas por endereço de e-mail em cada janela de 30 minutos.

Validar um token de redefinição de senha

GET/v1/auth/reset/{token}Unauthenticated

Verifica um token de redefinição sem consumi-lo. Autenticação não é necessária. Retorna um objeto validade de redefinição de senha.

Parâmetros de caminho

Campo	Tipo	Descrição
token	string	O token de redefinição de senha, exatamente 64 caracteres

Um token bem formado que é desconhecido, já consumido ou vinculado a uma conta excluída retorna o mesmo objeto com valid definido como falso.

A validade não garante que a redefinição seja bem-sucedida

A verificação resolve o token e confirma que sua conta existe e não foi excluída. A própria redefinição ainda recusa um token válido para uma conta de bot, para uma conta sob suspensão temporária ativa ou para uma senha de substituição no corpus de senhas vazadas.

Resposta

Status	Corpo	Condição
200	objeto validade de redefinição de senha	O token bem formado foi verificado
400	resposta de erro	O parâmetro do caminho do token falha na validação
403	resposta de erro	A imposição de SSO rejeita a operação
429	resposta de limite de taxa	A rota ou o bucket global nega a solicitação
500	resposta de erro	Ocorre uma falha interna inesperada
503	resposta de erro	A instância está em seu limite máximo de solicitações em andamento

Efeitos colaterais

Esta leitura não consome o token nem altera o estado da conta. Nenhum Dispatch do Gateway é emitido.

O token viaja no caminho

Um token no caminho chega a logs de proxy, histórico do navegador e cabeçalhos referrer. Um cliente DEVE ler o token do link de recuperação e enviá-lo nesta única solicitação, e NÃO DEVE rotear o navegador do usuário para o caminho da API diretamente.

Limite de taxa

20 solicitações por minuto, no bucket auth:reset:validate.

Redefinir uma senha

POST/v1/auth/resetUnauthenticated

Consome um token de redefinição válido e substitui a senha da conta, depois emite uma nova sessão ou um desafio MFA. Autenticação não é necessária. Retorna uma resposta de token de autenticação quando a conta não possui um segundo fator, e uma resposta de desafio MFA quando possui.

Corpo JSON

Campo	Tipo	Descrição
token	string	O token de redefinição de senha, exatamente 64 caracteres
password1	string	A senha substituta (8-256 caracteres)

¹ A senha é verificada no corpus público de senhas vazadas antes do token ser gasto, e uma correspondência retorna o código de campo PASSWORD_IS_TOO_COMMON

Um token desconhecido ou já consumido e um token vinculado a uma conta excluída retornam o código de campo INVALID_OR_EXPIRED_RESET_TOKEN. Uma suspensão temporária ativa retorna 403 ACCOUNT_SUSPENDED_TEMPORARILY. Uma suspensão permanente retorna o código de campo INVALID_OR_EXPIRED_RESET_TOKEN e nunca 403 ACCOUNT_SUSPENDED_PERMANENTLY. Uma conta de bot retorna 403 BOT_USER_AUTH_ENDPOINT_ACCESS_DENIED.

As senhas são verificadas em relação a um corpus de senhas vazadas, como ocorre durante o registro e a reversão de e-mail.

Redefinir uma senha revoga todas as sessões existentes

Uma redefinição bem-sucedida encerra todas as sessões de autenticação da conta, incluindo a que qualquer outro dispositivo está mantendo. Em seguida, emite uma nova sessão. Uma conta com um segundo fator recebe um ticket MFA, e a conclusão do MFA com esse ticket cria a sessão.

Resposta

Status	Corpo	Condição
200	resposta de token de autenticação | resposta de desafio MFA	A senha foi substituída
400	resposta de erro	O corpo, token ou senha de substituição é inválido
403	resposta de erro	A imposição de SSO, uma conta de bot ou uma suspensão temporária ativa rejeita a mutação
429	resposta de limite de taxa	A rota ou o bucket global nega a solicitação
500	resposta de erro	Ocorre uma falha interna inesperada
503	resposta de erro	A instância está em seu limite máximo de solicitações em andamento

Efeitos colaterais

A operação substitui a senha, registra a hora da mudança, limpa uma suspensão temporária expirada, encerra todas as sessões de autenticação na conta e consome o token de redefinição apresentado. Cada sessão encerrada perde sua sessão do Gateway, conforme afirma o comportamento compartilhado. Outros tokens de redefinição pendentes não são invalidados, portanto, um segundo link de recuperação emitido anteriormente ainda funciona.

Uma conta sem um segundo fator recebe, então, uma nova sessão e seu token. Uma conta com um segundo fator recebe, em vez disso, um ticket MFA de cinco minutos, e a conclusão do MFA cria a sessão.

Limite de taxa

10 solicitações por minuto, no bucket auth:reset.

Reverter uma alteração de e-mail

POST/v1/auth/email-revertUnauthenticated

Consome o token entregue no endereço de e-mail anterior, restaura esse endereço, substitui a senha, encerra todas as sessões de autenticação e limpa todos os segundos fatores. O endereço IP que fez a solicitação se torna o único endereço IP autorizado. Retorna uma resposta de token de autenticação. Emite um evento de Gateway User Update.

O token é válido por 24 horas após a alteração de endereço que o emitiu.

Corpo JSON

Campo	Tipo	Descrição
token	string	O token de reversão de e-mail, exatamente 64 caracteres
password1	string	A senha substituta (8-256 caracteres)

¹ O valor torna-se a nova senha da conta, e o Decoding Chat o verifica contra o corpus público de senhas vazadas, retornando o código de campo PASSWORD_IS_TOO_COMMON em caso de correspondência

A reversão destrói todas as outras credenciais

Concluir uma reversão encerra todas as sessões de autenticação e limpa o registro de segundo fator inteiro da conta. O conjunto de endereços IP autorizados passa a ser apenas o endereço IP da solicitação. Qualquer outro dispositivo, chave de acesso ou código de backup mantido por quem fez a alteração original do e-mail para de funcionar imediatamente e nada disso pode ser restaurado.

Um token desconhecido ou já consumido, e um token vinculado a uma conta que não existe mais, retornam o código de campo INVALID_OR_EXPIRED_REVERT_TOKEN. A suspensão da conta retorna 403 ACCOUNT_SUSPENDED_TEMPORARILY ou 403 ACCOUNT_SUSPENDED_PERMANENTLY, e uma conta de bot retorna 403 BOT_USER_AUTH_ENDPOINT_ACCESS_DENIED.

O Decoding Chat verifica a senha de substituição no mesmo corpus de senhas vazadas descrito em redefinir uma senha antes de gastar o token.

Resposta

Status	Corpo	Condição
200	resposta de token de autenticação	O endereço e a recuperação de credenciais foram concluídos
400	resposta de erro	O corpo, o token ou a senha de substituição é inválido
403	resposta de erro	A imposição de SSO, uma conta de bot ou suspensão de conta rejeita a mutação
429	resposta de limite de taxa	A rota ou o bucket global nega a solicitação
500	resposta de erro	Ocorre uma falha interna inesperada
503	resposta de erro	A instância está em seu limite máximo de solicitações em andamento

Efeitos colaterais

O endereço de e-mail anterior se torna verificado e a senha de substituição se torna a senha da conta. Todas as outras sessões, segundos fatores e endereços IP autorizados são removidos. Apenas o endereço IP da solicitação permanece autorizado.

A conta recebe User Update. As sessões de Gateway existentes terminam conforme descrito em comportamento compartilhado, e a resposta retorna uma nova sessão de autenticação.

Limite de taxa

10 solicitações por minuto, no bucket auth:email_revert.

Listar sessões de autenticação

GET/v1/auth/sessions

Lista cada sessão de autenticação ativa pertencente à conta autenticada, com as atividades mais recentes primeiro. Requer um token de sessão de usuário para um usuário comum. Retorna uma matriz de objetos sessão de autenticação.

A solicitação não tem corpo e não requer parâmetros.

Resposta

Status	Corpo	Condição
200	array[objeto sessão de autenticação]	As sessões ativas foram lidas
401	resposta de erro	A credencial de sessão do usuário está ausente ou é inválida
403	resposta de erro	A credencial é um token de bot ou um token bearer OAuth2
429	resposta de limite de taxa	A rota ou o bucket global nega a solicitação
500	resposta de erro	Ocorre uma falha interna inesperada
503	resposta de erro	A instância está em seu limite máximo de solicitações em andamento

Efeitos colaterais

Esta leitura não altera o estado da sessão. Nenhum Dispatch do Gateway é emitido.

Limite de taxa

40 solicitações por 10 segundos, no bucket auth:sessions.

Encerrar sessões de autenticação

POST/v1/auth/sessions/logoutMFA

Exclui as sessões de autenticação nomeadas. Requer um token de sessão de usuário para um usuário comum e modo sudo. Retorna 204 sem nenhum corpo.

O chamador DEVE enviar um token sudo válido no cabeçalho X-Fluxer-Sudo-Mode-JWT, ou fornecer uma senha ou prova MFA no corpo.

Corpo JSON

Campo	Tipo	Descrição
session_id_hashes1	array[string]	Os resumos de sessão a serem excluídos (máx. 100 entradas)
password?2	string	A prova de senha para uma conta sem um segundo fator (8-256 caracteres)
mfa_method?3	string	O método de prova, seja totp ou webauthn
mfa_code?	string	O código do autenticador ou um código de backup não consumido quando o método é totp (1-32 caracteres)
webauthn_response?	objeto asserção WebAuthn	A asserção quando o método é webauthn
webauthn_challenge?	string	O desafio vinculado à asserção do modo sudo

¹ Cada valor é a string base64url id_hash de listar sessões de autenticação. O Decoding Chat ignora um identificador desconhecido, e uma matriz vazia não exclui nada e ainda retorna 204

² A senha é aceita apenas quando a conta não possui um segundo fator, e um valor que não corresponda retorna o código de campo INVALID_PASSWORD

³ A prova MFA é aceita apenas quando a conta possui um segundo fator. Qualquer falha retorna o código de campo INVALID_MFA_CODE em mfa_code, e uma prova bem-sucedida emite um novo token sudo

Um método totp lê mfa_code como um código de autenticador e aceita um código de backup não consumido em seu lugar. Um método webauthn lê webauthn_response e webauthn_challenge juntos e aceita apenas um desafio que foi emitido para o contexto sudo.

O chamador pode excluir sua própria sessão

A operação exclui exatamente as sessões identificadas pelos valores id_hash fornecidos. Um cliente que deseja manter sua própria sessão DEVE omitir o id_hash da entrada cujo current é verdadeiro. A revogação da credencial de chamada ainda retorna 204.

Uma prova ausente ou inutilizável retorna 403 SUDO_MODE_REQUIRED, cujo corpo de erro tem membros de nível superior has_mfa e methods, e methods informa se totp e webauthn estão disponíveis.

Uma conta não reivindicada não precisa de prova

Uma conta que não tem senha nem um segundo fator satisfaz o modo sudo sem prova no corpo e sem token sudo, e o Decoding Chat não emite nenhum. Todas as outras contas DEVEM apresentar um token sudo válido, uma senha ou uma prova MFA.

Resposta

Status	Corpo	Condição
204	vazio	Toda sessão nomeada estava ausente ou foi excluída
400	resposta de erro	O corpo ou a prova fornecida é inválida
401	resposta de erro	A credencial de sessão do usuário está ausente ou é inválida
403	resposta de erro	A credencial é um token de bot ou um token bearer OAuth2, ou é necessário o modo sudo
429	resposta de limite de taxa	A rota ou o bucket global nega a solicitação
500	resposta de erro	Ocorre uma falha interna inesperada
503	resposta de erro	A instância está em seu limite máximo de solicitações em andamento

Efeitos colaterais

Cada sessão nomeada é excluída e perde sua sessão do Gateway, conforme afirma o comportamento compartilhado. Uma nova prova MFA emite um novo token sudo, enquanto um token de entrada aceito é ecoado inalterado. O Decoding Chat define qualquer token que resulte no cabeçalho de resposta X-Fluxer-Sudo-Mode-JWT. Uma prova de senha em uma conta sem segundo fator não emite token, então o cabeçalho não é definido a menos que a solicitação já tivesse um. Nenhum Dispatch do Gateway é emitido.

Limite de taxa

20 solicitações por 10 segundos, no bucket auth:sessions:logout.

Autorizar um endereço IP

POST/v1/auth/authorize-ipUnauthenticated

Consome o token de autorização entregue por e-mail, autoriza o endereço IP do cliente pendente e conclui o login que aguardava. Autenticação não é necessária. Retorna 204 sem nenhum corpo.

Corpo JSON

Campo	Tipo	Descrição
token	string	O token de autorização entregue por e-mail

Um token desconhecido, expirado, já consumido ou que não corresponda à conta retorna o código de campo INVALID_OR_EXPIRED_AUTHORIZATION_TOKEN. Um token que se resolve para uma conta que não existe mais retorna 404 UNKNOWN_USER, e aquele que se resolve para uma conta de bot retorna 403 BOT_USER_AUTH_ENDPOINT_ACCESS_DENIED. A criação da sessão também rejeita uma conta que não foi admitida ou está suspensa, com os códigos listados em fazer login com uma senha.

Resposta

Status	Corpo	Condição
204	vazio	O endereço IP foi autorizado e o novo token de sessão é legível por meio da pesquisa de autorização de IP
400	resposta de erro	O corpo ou token de autorização é inválido
403	resposta de erro	A imposição de SSO rejeita a operação ou o token resolve para uma conta de bot
404	resposta de erro	O token se resolve para uma conta que não existe mais
429	resposta de limite de taxa	A rota ou o bucket global nega a solicitação
500	resposta de erro	Ocorre uma falha interna inesperada
503	resposta de erro	A instância está em seu limite máximo de solicitações em andamento

Efeitos colaterais

A operação adiciona o endereço IP do cliente pendente ao conjunto autorizado da conta e cria uma sessão de autenticação. Essa sessão assume o endereço IP, o user agent e o sistema operacional reportado capturados quando o login foi tentado. Consome o token de autorização e o ticket do login pendente.

O token de sessão é então publicado em relação ao ticket e permanece legível por pesquisa de autorização de IP durante 60 segundos. O chamador desta operação recebe 204 e nenhum token próprio. Nenhum Dispatch do Gateway é emitido.

Limite de taxa

5 solicitações por minuto, no bucket auth:authorize_ip.

Reenviar autorização de IP

POST/v1/auth/ip-authorization/resendUnauthenticated

Envia novamente a mensagem de autorização para um ticket de autorização IP pendente. Autenticação não é necessária. Retorna 204 sem nenhum corpo.

Corpo JSON

Campo	Tipo	Descrição
ticket1	string	O ticket retornado pelo erro de login IP_AUTHORIZATION_REQUIRED

¹ O reenvio reutiliza o token de autorização já vinculado ao ticket, para que uma mensagem entregue por um envio anterior permaneça válida

Um ticket desconhecido ou expirado retorna o código de campo INVALID_OR_EXPIRED_AUTHORIZATION_TICKET. Um reenvio em menos de 30 segundos após a emissão do ticket retorna 429 IP_AUTHORIZATION_RESEND_COOLDOWN com um cabeçalho Retry-After e um resend_available_in de nível superior em segundos. Um segundo reenvio retorna 400 IP_AUTHORIZATION_RESEND_LIMIT_EXCEEDED.

Uma resposta perdida ainda gasta o reenvio

Não há chave de repetição. Um cliente que perde a resposta não pode dizer se a mensagem foi entregue, e uma tentativa retorna 400 IP_AUTHORIZATION_RESEND_LIMIT_EXCEEDED uma vez que a primeira solicitação marcou o reenvio como usado.

Resposta

Status	Corpo	Condição
204	vazio	A mensagem foi enviada novamente
400	resposta de erro	O corpo ou o ticket é inválido, ou o único reenvio do ticket já foi usado
403	resposta de erro	A imposição de SSO rejeita a operação
429	resposta de limite de taxa	Um bucket de rota ou global nega a solicitação, ou o atraso de reenvio não passou
500	resposta de erro	Ocorre uma falha interna inesperada
503	resposta de erro	A instância está em seu limite máximo de solicitações em andamento

Efeitos colaterais

O Decoding Chat envia a mensagem de autorização ao endereço associado à tentativa de login e marca o único reenvio do ticket usado independentemente de a entrega ser bem-sucedida. Nenhum estado da conta muda. Nenhum Dispatch do Gateway é emitido.

Limite de taxa

5 solicitações por minuto, no bucket auth:ip_authorization_resend, e cada ticket permite exatamente um reenvio, não antes de 30 segundos após a emissão do ticket.

Pesquisar autorização de IP

GET/v1/auth/ip-authorization/pollUnauthenticated

Lê o resultado do login associado a um ticket de autorização de IP. Autenticação não é necessária. Retorna um objeto pesquisa de autorização por IP.

Parâmetros de consulta

Campo	Tipo	Descrição
ticket	string	O ticket retornado pelo erro de login IP_AUTHORIZATION_REQUIRED

Um ticket desconhecido ou expirado retorna o código de campo INVALID_OR_EXPIRED_AUTHORIZATION_TICKET, que também é o resultado assim que a retenção do resultado de 60 segundos tiver passado.

Ler o resultado concluído não o consome

Pesquisas repetidas retornam o mesmo token, então quem tiver o ticket dentro da janela de retenção de 60 segundos pode lê-lo. Um token concluído é uma credencial de sessão ativa a partir do momento em que aparece pela primeira vez.

Resposta

Status	Corpo	Condição
200	objeto pesquisa de autorização por IP	O ticket foi lido
400	resposta de erro	A consulta é malformada ou o ticket é desconhecido ou expirado
403	resposta de erro	A imposição de SSO rejeita a operação
404	resposta de erro	O resultado concluído nomeia uma conta que não existe mais, retornando UNKNOWN_USER
429	resposta de limite de taxa	A rota ou o bucket global nega a solicitação
500	resposta de erro	Ocorre uma falha interna inesperada
503	resposta de erro	A instância está em seu limite máximo de solicitações em andamento

Limite de taxa

60 solicitações por minuto, no bucket auth:ip_authorization_poll.

Obter sugestões de nome de usuário

POST/v1/auth/username-suggestionsUnauthenticated

Deriva candidatos a nome de usuário de um nome de exibição. Autenticação não é necessária. Retorna um objeto de sugestões de nome de usuário.

A rota compartilha o bucket auth:register, que permite 10 solicitações a cada 10 segundos.

Corpo JSON

Campo	Tipo	Descrição
global_name	string	O nome de exibição após a normalização (1-32 caracteres)

Um candidato retornado pode ser pego antes do uso

A operação não verifica a disponibilidade e não retém nada. O registro aloca seu próprio discriminador independentemente da sugestão.

Resposta

Status	Corpo	Condição
200	objeto sugestões de nome de usuário	Os candidatos foram gerados
400	resposta de erro	O corpo ou o nome de exibição é inválido
403	resposta de erro	A imposição de SSO rejeita a operação
429	resposta de limite de taxa	A rota ou o bucket global nega a solicitação
500	resposta de erro	Ocorre uma falha interna inesperada
503	resposta de erro	A instância está em seu limite máximo de solicitações em andamento

Efeitos colaterais

Esta leitura não reserva nenhum nome de usuário e não altera nenhum estado da conta. Nenhum Dispatch do Gateway é emitido.

Iniciar handoff para desktop

POST/v1/auth/handoff/initiateUnauthenticated

Cria um handoff pendente e retorna o código que o dispositivo iniciador mostra a um dispositivo já conectado. Autenticação não é necessária. Retorna um objeto iniciação de handoff.

A solicitação não tem corpo. O Decoding Chat deriva os metadados do dispositivo exibidos para o dispositivo aprovador a partir da própria solicitação.

Cabeçalhos da solicitação

Campo	Tipo	Descrição
User-Agent?	string	A string de cliente apresentada ao dispositivo aprovador e gravada na sessão que o handoff cria
X-Fluxer-Client-Properties?	string	O JSON codificado em base64 com o os do cliente de relatório, lido apenas para um User-Agent nativo do Decoding Chat

Resposta

Status	Corpo	Condição
200	objeto iniciação de handoff	Uma solicitação de handoff foi criada
429	resposta de limite de taxa	A rota ou o bucket global nega a solicitação
500	resposta de erro	Ocorre uma falha interna inesperada
503	resposta de erro	A instância está em seu limite máximo de solicitações em andamento

Efeitos colaterais

O handoff permanece pendente por cinco minutos e registra o endereço IP do cliente, o user agent e o sistema operacional reportado do dispositivo iniciador. A iniciação não cria nenhuma sessão. Nenhum Dispatch do Gateway é emitido.

Limite de taxa

10 solicitações por minuto, no bucket auth:handoff:initiate.

Obter informações de handoff de desktop

GET/v1/auth/handoff/{code}/infoUnauthenticated

Descreve o dispositivo que iniciou um handoff pendente para que o dispositivo aprovador possa exibi-lo antes de aprovar, e marca o código como aprovável. Autenticação não é necessária. Retorna um objeto de informações de handoff.

O Decoding Chat conta as tentativas de código com falha em relação ao endereço IP do cliente e o bloqueia após 5 falhas em 15 minutos. Um resultado pendente não registra nenhuma falha, enquanto um código desconhecido ou expirado registra uma.

Parâmetros de caminho

Campo	Tipo	Descrição
code1	string	O código do handoff

¹ O Decoding Chat normaliza o valor removendo hifens e espaços em branco e colocando o restante em maiúsculas, e o resultado normalizado tem exatamente 12 caracteres do alfabeto de handoff

Uma pesquisa bem-sucedida torna o código completável

Ler as informações do handoff marca o código como inspecionado, mas não aprova a transferência. Concluir handoff para desktop rejeita um código que nunca foi inspecionado. Um cliente aprovador DEVE mostrar as informações do dispositivo iniciador e obter confirmação explícita do usuário antes da conclusão.

Qualquer um que possa acessar a API e conheça o código pode marcá-lo como inspecionado. Recusar a solicitação em um cliente descarta apenas o que aquele cliente está mostrando, e o estado inspecionado permanece até que o handoff seja concluído ou o código expire.

Um código que não tem exatamente 12 caracteres do alfabeto de handoff após hifens e espaços em branco serem removidos retorna 400 INVALID_HANDOFF_CODE. Tanto um código cujas três pesquisas já estão esgotadas quanto uma solicitação de um endereço IP de cliente que esgotou sua permissão de tentativa com falha retornam o mesmo código de erro. Um código desconhecido ou expirado retorna 200 com o status expired e registra uma tentativa com falha.

Resposta

Status	Corpo	Condição
200	objeto informações de handoff	O estado pendente ou expirado foi lido
400	resposta de erro	O código está malformado, seu orçamento de pesquisa acabou ou a permissão de tentativa do IP do cliente está esgotada
429	resposta de limite de taxa	A rota ou o bucket global nega a solicitação
500	resposta de erro	Ocorre uma falha interna inesperada
503	resposta de erro	A instância está em seu limite máximo de solicitações em andamento

Efeitos colaterais

Uma pesquisa bem-sucedida consome uma das três pesquisas do código e permite concluir handoff para desktop. Um resultado expirado conta como uma tentativa falha. Não ocorrem alterações no estado da conta nem Dispatch do Gateway.

Limite de taxa

10 solicitações por minuto, no bucket auth:handoff:info, e cada código permite no máximo três pesquisas bem-sucedidas no total, contadas no próprio código.

Concluir handoff para desktop

POST/v1/auth/handoff/complete

Aprova um handoff pendente emitindo uma nova sessão para o dispositivo iniciador sob a autoridade de uma ativa. Requer o próprio token de sessão de usuário do dispositivo aprovador. Retorna 204 sem nenhum corpo.

O Decoding Chat lê esse token no cabeçalho Authorization ou no campo de corpo token quando o corpo fornece um.

Corpo JSON

Campo	Tipo	Descrição
code1	string	O código de handoff mostrado pelo dispositivo iniciador
token?2	string	O próprio token de sessão de usuário do dispositivo aprovador
user_id3	snowflake	A conta à qual a sessão de aprovação pertence

¹ O código usa o mesmo contrato de normalização de obter informações de handoff de desktop, e apenas um código que a operação já inspecionou é aceito

² O token do corpo tem precedência sobre o cabeçalho Authorization, e uma solicitação que não fornece nenhum dos dois retorna 401 UNAUTHORIZED

³ Um token fornecido que se resolve em uma conta diferente retorna SESSION_TOKEN_MISMATCH

O token de aprovação pode viajar no corpo

O envio do token em token coloca uma credencial ativa em uma carga JSON. Um cliente DEVE usar o cabeçalho Authorization e omitir o token.

Um token que se resolve sem sessão ativa retorna 401 INVALID_TOKEN. Um código malformado, desconhecido, concluído ou não inspecionado retorna 400 INVALID_HANDOFF_CODE, assim como uma permissão de tentativa com falha esgotada. Um código expirado retorna INVALID_HANDOFF_CODE ou HANDOFF_CODE_EXPIRED. Inicie um novo handoff em qualquer um dos casos.

A criação de sessão também pode retornar 403 BOT_USER_AUTH_SESSION_CREATION_DENIED para uma conta de bot e 403 REGISTRATION_PENDING_APPROVAL ou 403 REGISTRATION_REJECTED para uma conta que não foi admitida. Uma conta suspensa retorna os códigos de suspensão listados em fazer login com uma senha.

Resposta

Status	Corpo	Condição
204	vazio	O handoff foi concluído
400	resposta de erro	O corpo, o código, o estado de expiração ou a propriedade da sessão é inválido
401	resposta de erro	A credencial de aprovação está ausente, é inválida ou foi revogada
403	resposta de erro	A sessão de aprovação pertence a um bot ou a uma conta aguardando aprovação ou rejeitada
404	resposta de erro	A sessão de aprovação resolve para uma conta que não existe mais
429	resposta de limite de taxa	A rota ou o bucket global nega a solicitação
500	resposta de erro	Ocorre uma falha interna inesperada
503	resposta de erro	A instância está em seu limite máximo de solicitações em andamento

Efeitos colaterais

A conclusão cria uma nova sessão de autenticação para o dispositivo iniciador e publica seu token em relação ao código. O token permanece legível por meio de obter status de handoff de desktop por qualquer tempo que reste dos cinco minutos do handoff. A conclusão também descarta o handoff pendente, de modo que o código não pode ser concluído uma segunda vez e um posterior obter informações de handoff de desktop relata expired.

A sessão de aprovação permanece válida. A nova sessão assume o endereço IP do cliente, o user agent e o sistema operacional reportado do dispositivo iniciador no registro de handoff. Nenhum Dispatch do Gateway é emitido.

Limite de taxa

10 solicitações por minuto, no bucket auth:handoff:complete, e um endereço IP do cliente é bloqueado após 5 tentativas de código com falha em 15 minutos.

Obter status de handoff de desktop

GET/v1/auth/handoff/{code}/statusUnauthenticated

Informa o estado de um handoff ao dispositivo que o iniciou. Autenticação não é necessária. Retorna um objeto status de handoff.

Parâmetros de caminho

Campo	Tipo	Descrição
code	string	O código de handoff, usando o mesmo contrato de normalização de obter informações de handoff de desktop

Esta rota nunca retorna o token

O token precisa de poll_secret, portanto, um handoff concluído reporta pending aqui. Leia-o com obter status de handoff de desktop com o segredo de pesquisa.

O código é a única credencial que esta rota verifica. O dispositivo iniciador DEVE consultar a própria conclusão.

Resposta

Status	Corpo	Condição
200	objeto status de handoff	O estado foi lido ou um código desconhecido foi relatado como expirado
400	resposta de erro	O código está malformado, retornando INVALID_HANDOFF_CODE
429	resposta de limite de taxa	A rota ou o bucket global nega a solicitação
500	resposta de erro	Ocorre uma falha interna inesperada
503	resposta de erro	A instância está em seu limite máximo de solicitações em andamento

Efeitos colaterais

Uma pesquisa deixa o handoff inalterado. Uma pesquisa contra um handoff concluído registra uma tentativa falha para o endereço IP da pesquisa, porque esta rota não apresenta nenhum poll_secret. Nenhuma alteração no estado da conta e nenhum Dispatch do Gateway é emitido.

Limite de taxa

60 solicitações por minuto, no bucket auth:handoff:status.

Obter status de handoff de desktop com o segredo da pesquisa

POST/v1/auth/handoff/{code}/statusUnauthenticated

Relata o estado de um handoff e entrega o novo token de sessão uma vez, a um chamador que apresente o segredo de pesquisa emitido na iniciação. Autenticação não é necessária. Retorna um objeto status de handoff.

Parâmetros de caminho

Campo	Tipo	Descrição
code	string	O código de handoff, usando o mesmo contrato de normalização de obter informações de handoff de desktop

Corpo JSON

Campo	Tipo	Descrição
poll_secret	string	O segredo retornado por iniciar handoff para desktop

O status de concluído é entregue exatamente uma vez

O token é retornado uma vez. Pesquisas posteriores relatam expired, então o dispositivo iniciador DEVE retê-lo quando recebido pela primeira vez.

Um segredo que não corresponda relata pending e registra uma tentativa com falha para o endereço IP da pesquisa. A rota não relata nenhum erro distinto para um segredo errado, portanto, um chamador não pode distinguir um segredo errado de um handoff que o dispositivo de aprovação não concluiu.

Resposta

Status	Corpo	Condição
200	objeto status de handoff	O estado foi lido ou um código desconhecido foi relatado como expirado
400	resposta de erro	O código está malformado, retornando INVALID_HANDOFF_CODE
404	resposta de erro	O handoff concluído nomeia uma conta que não existe mais, retornando UNKNOWN_USER
429	resposta de limite de taxa	A rota ou o bucket global nega a solicitação
500	resposta de erro	Ocorre uma falha interna inesperada
503	resposta de erro	A instância está em seu limite máximo de solicitações em andamento

Efeitos colaterais

Recuperar o token conclui o handoff. Outras pesquisas o deixam inalterado. Nenhum Dispatch do Gateway é emitido.

Limite de taxa

60 solicitações por minuto, no bucket auth:handoff:status.

Cancelar um handoff para desktop

DELETE/v1/auth/handoff/{code}Unauthenticated

Descarta um handoff e tudo armazenado contra seu código. Autenticação não é necessária. Retorna 204 sem nenhum corpo.

Parâmetros de caminho

Campo	Tipo	Descrição
code	string	O código de handoff, usando o mesmo contrato de normalização de obter informações de handoff de desktop

Corpo JSON

Campo	Tipo	Descrição
poll_secret	string	O segredo retornado por iniciar handoff para desktop

Um código desconhecido ou já expirado não tem segredo armazenado, então ele retorna 400 INVALID_HANDOFF_CODE.

Cancelar requer o segredo da pesquisa

A rota exige o poll_secret que o iniciar handoff para desktop retornou, enviado no corpo JSON. Um segredo errado retorna 400 INVALID_HANDOFF_CODE, então uma parte que conhece apenas o código não pode cancelar o handoff. Após um cancelamento, o dispositivo iniciador lê o status expired.

Resposta

Status	Corpo	Condição
204	vazio	O handoff foi descartado
400	resposta de erro	O código é malformado ou o segredo não corresponde, retornando INVALID_HANDOFF_CODE
429	resposta de limite de taxa	A rota ou o bucket global nega a solicitação
500	resposta de erro	Ocorre uma falha interna inesperada
503	resposta de erro	A instância está em seu limite máximo de solicitações em andamento

Efeitos colaterais

O cancelamento impede qualquer recuperação adicional de token, mas não revoga uma sessão já criada por conclusão. Nenhum Dispatch do Gateway é emitido.

Limite de taxa

10 solicitações por minuto, no bucket auth:handoff:cancel.