Autenticação multifator

A autenticação multifator solicita uma segunda prova de identidade após a senha da conta. O Decoding Chat aceita um aplicativo autenticador TOTP e credenciais WebAuthn, como uma passkey. Um código de backup de uso único funciona no lugar de um código TOTP, e o modo sudo reutiliza esses fatores para proteger todas as operações sensíveis à segurança na API.

Todas as rotas aqui requerem uma sessão de usuário que não seja de bot. O Decoding Chat rejeita uma conta em estado de atividade suspeita com 403 ACCOUNT_SUSPICIOUS_ACTIVITY, inclusive nas rotas sudo.

Um desafio é de uso único e vinculado ao contexto

O Decoding Chat consome um código de backup, um desafio de registro WebAuthn e um desafio sudo WebAuthn no primeiro uso. Um desafio está vinculado ao usuário para o qual foi emitido e à operação para a qual foi emitido: registro, sudo, login MFA ou login descobrível. Ele expira após cinco minutos, portanto um desafio de registro não pode ser resgatado como uma asserção sudo.

Parâmetros TOTP

O Decoding Chat valida um código TOTP como uma senha de uso único HMAC-SHA-1 de seis dígitos ao longo de um intervalo de tempo de 30 segundos contado a partir do Unix epoch. Ele aceita um intervalo de tempo de diferença de relógio (clock skew) para mais ou para menos. Um código enviado possui exatamente seis dígitos decimais, e o Decoding Chat rejeita qualquer outro valor. O segredo compartilhado é Base32, e o Decoding Chat ignora espaços em branco, hifens e preenchimento (padding) à direita ao decodificá-lo.

O cliente gera o segredo, apresenta-o ao usuário e o envia com um código derivado dele ao chamar Ativar MFA TOTP. O Decoding Chat nunca gera ou retorna um segredo TOTP.

Um código TOTP pode passar duas vezes

O Decoding Chat rejeita um código aceito por 30 segundos se ele for enviado novamente. A diferença de relógio mantém um código válido por até 90 segundos, então ele pode passar novamente assim que esses 30 segundos passarem. Aguarde o próximo intervalo de tempo.

Contrato de códigos de backup

Regenerar códigos de backup exclui o conjunto armazenado e então emite exatamente 10 substitutos, de modo que qualquer código que o usuário já tenha salvo para de funcionar.

Ativar o TOTP emite 10 códigos sem excluir nada primeiro. Uma conta que já gerou um conjunto por meio de Listar códigos de backup MFA enquanto não possuía nenhum segredo TOTP mantém esses códigos ao lado dos 10 que a resposta de ativação retorna. Todos permanecem resgatáveis. Desativar o TOTP exclui todos os códigos de backup sem emitir substitutos.

Listar códigos de backup MFA lê o conjunto atual de volta a qualquer momento e relata quais códigos já foram consumidos. O consumo de um código é irreversível. Uma conta que não pode provar o modo sudo lê o mesmo conjunto por meio do desafio de códigos de backup.

Um código de backup tem apenas estes pontos de entrada: o campo mfa_code do objeto de verificação sudo com mfa_method definido como totp, o campo code de Desativar MFA TOTP e o campo code de concluir login com TOTP. Todos os outros campos de código o rejeitam. Todos aceitam um código de autenticador atual ou um código de backup não consumido. Ativar MFA TOTP valida apenas contra o segredo que está sendo inscrito.

Cada ponto de entrada requer que a conta possua um segredo TOTP. Uma conta cujo único autenticador é o WebAuthn não possui um segredo TOTP, de modo que nenhum dos pontos de entrada aceita um código de backup, embora a conta ainda possa regenerar o conjunto.

Um código de backup em maiúsculas com espaços ainda corresponde

O Decoding Chat converte para minúsculas o valor enviado e cada código armazenado, depois remove todos os caracteres fora de a-z e 0-9. abcdefgh e AbCd EfGh correspondem ao código emitido abcd-efgh.

Segredos de autenticador são credenciais

Mantenha o segredo TOTP e todos os códigos de backup fora de logs, análises, URLs e outras superfícies visíveis para terceiros. Um conjunto regenerado substitui o anterior imediatamente, portanto deixe o usuário armazenar o novo conjunto antes de descartar a resposta.

Desafio de códigos de backup

Uma conta que perdeu seus códigos de backup salvos lê o conjunto de volta por meio de um desafio enviado por email. Iniciar desafio de códigos de backup MFA abre um ticket e envia um código por email. Verificar código de desafio de códigos de backup MFA troca esse código pelo conjunto atual e uma prova. Regenerar códigos de backup MFA então apresenta o ticket e a prova para substituir o conjunto. Reenviar código de desafio de códigos de backup MFA envia um novo código a qualquer momento antes da verificação.

O modo sudo não se aplica a nenhuma das quatro operações, de modo que um usuário que não possui mais o aplicativo autenticador ainda alcança os códigos por meio do endereço de email. A conta precisa de um endereço de email verificado e do TOTP ativado. Apenas Iniciar desafio de códigos de backup MFA verifica o endereço, e Regenerar códigos de backup MFA verifica o TOTP uma segunda vez.

Um ticket é um UUID versão 4 válido por 30 minutos após o início do desafio, o reenvio do código ou a verificação do código. A regeneração não o estende. Um ticket expirado, desconhecido ou de outra conta falha com INVALID_OR_EXPIRED_TICKET.

Um código de verificação possui oito caracteres extraídos do alfabeto latino maiúsculo e de dígitos decimais, escritos como dois grupos de quatro caracteres separados por um hífen. Um código é válido por 10 minutos a partir do momento em que é enviado, e cada envio substitui o código que o envio anterior emitiu.

Um código em minúsculas sem hífen ainda corresponde

O Decoding Chat apara (trims) o valor enviado, converte-o para maiúsculas e remove cada hífen antes de compará-lo. Um valor errado falha com INVALID_VERIFICATION_CODE no caminho code.

A verificação consome o código e emite uma prova como um UUID versão 4. Uma prova incorreta falha com INVALID_PROOF_TOKEN. Um ticket sem prova falha com INVALID_OR_EXPIRED_TICKET em verification_proof.

Cada falha de ticket, código e prova nomeada aqui chega como HTTP 400, cujo código de nível superior é INVALID_FORM_BODY. O valor nomeado é o code de uma entrada do objeto de erro de validação, e o path dessa entrada é o campo ao qual ele pertence.

Cada operação passa por seu próprio bucket de rota e, separadamente, por um dos controles abaixo. Esgotar qualquer um deles produz HTTP 429 mesmo quando o outro tem espaço.

Controle	Permissão	Operação
Início do desafio	3 envios por 15 minutos para cada conta	Iniciar desafio de códigos de backup MFA
Reenvio do desafio	3 envios por 15 minutos para cada conta	Reenviar código de desafio de códigos de backup MFA
Verificação de código	5 tentativas por 15 minutos para cada ticket	Verificar código de desafio de códigos de backup MFA
Regeneração	5 tentativas por 15 minutos para cada ticket	Regenerar códigos de backup MFA

O Decoding Chat recusa um reenvio por 30 segundos após o envio anterior no mesmo ticket. Essa recusa é HTTP 429 com um Retry-After calculado a partir do momento em que o próximo envio ficar disponível. É independente do bucket de rota e dos controles de envio de 15 minutos.

Modo sudo

O modo sudo é uma prova de curta duração de que a pessoa em frente à sessão ainda é a titular da conta. Uma operação que exige isso aceita um cabeçalho de requisição X-Fluxer-Sudo-Mode-JWT válido ou os campos do objeto de verificação sudo dentro do corpo JSON.

Um token sudo dura cinco minutos e funciona apenas para a conta que o obteve, através das sessões dessa conta. Trate-o como opaco. Um novo token é emitido apenas após uma prova MFA de uma conta com um autenticador inscrito.

O cabeçalho ecoado repete o valor da requisição

Quando o Decoding Chat não emite um novo token, ele ecoa o valor X-Fluxer-Sudo-Mode-JWT da requisição de volta sem alterações e nunca o assina novamente, de modo que a janela de cinco minutos nunca é estendida. O Decoding Chat ecoa o valor mesmo quando ele falha na verificação.

A prova aceita depende dos autenticadores que a conta tem configurados.

Estado da conta	Prova aceita
Nenhum autenticador	password
Qualquer autenticador	mfa_method com seus campos correspondentes, pois password não é mais aceita
Nem um autenticador nem uma credencial de senha	Nada, e operações elegíveis para sudo passam

O método totp lê mfa_code como um código de autenticador atual ou um código de backup não consumido e exige que a conta possua um segredo TOTP. O método webauthn lê webauthn_response e webauthn_challenge juntos e exige uma credencial registrada.

Uma requisição que não possui uma prova aceita falha com 403 SUDO_MODE_REQUIRED. Seu corpo possui os membros do objeto de métodos do modo sudo, para que um cliente possa dizer qual prova solicitar ao usuário. Uma prova que está presente, mas incorreta, falha em vez disso com 400 INVALID_FORM_BODY e uma entrada de erro de validação. Uma senha incompatível produz o caminho password com o código INVALID_PASSWORD. Um código TOTP, código de backup ou asserção WebAuthn rejeitado produz o caminho mfa_code com o código INVALID_MFA_CODE, para que um cliente não possa dizer qual dos três foi rejeitado.

O método totp também consome uma permissão por conta de 10 tentativas de multifator a cada 15 minutos, compartilhada por toda operação restrita por sudo em todos os recursos. O Decoding Chat cobra a permissão antes de verificar o código, de forma que um código errado e um código correto consumam essa permissão. Um código correto zera o contador. Enquanto estiver esgotado, um código correto retorna a mesma entrada INVALID_MFA_CODE que um incorreto. O método webauthn não consome permissão alguma. As permissões de MFA de login na autenticação HTTP são contadas separadamente.

O Decoding Chat retorna um token emitido ou ecoado no cabeçalho de resposta X-Fluxer-Sudo-Mode-JWT. Um cliente o mantém e o envia no mesmo cabeçalho em todas as operações posteriores restritas por sudo.

Objeto de métodos do modo sudo

Em uma resposta de erro SUDO_MODE_REQUIRED, has_mfa e methods estão no nível superior do objeto de resposta de erro.

Estrutura

Campo	Tipo	Descrição
has_mfa	boolean	Se a conta tem o tipo de autenticador TOTP ou WebAuthn
methods	objeto de disponibilidade de método do modo sudo	Autenticadores que a conta pode apresentar

Objeto de disponibilidade de método do modo sudo

Estrutura

Campo	Tipo	Descrição
totp1	boolean	Se a conta tem um segredo TOTP e o tipo de autenticador TOTP
webauthn	boolean	Se a conta tem o tipo de autenticador WebAuthn

¹ Ambas as condições são necessárias, então uma conta que possui um segredo armazenado sem o tipo de autenticador relata false

Objeto de verificação sudo

Operações que exigem modo sudo mesclam esses campos em seu próprio corpo JSON. Todos os campos são opcionais na borda, porque a combinação aceita depende do estado da conta descrito no modo sudo.

Estrutura

Campo	Tipo	Descrição
password?1	string	Senha da conta (8-256 caracteres)
mfa_method?2	string	Método MFA, totp ou webauthn
mfa_code?3	string	Código do autenticador ou código de backup não consumido (1-32 caracteres)
webauthn_response?4	objeto de asserção WebAuthn	Asserção produzida para o desafio fornecido
webauthn_challenge?4	string	Desafio retornado por criar opções de autenticação sudo WebAuthn (1-256 caracteres)

¹ Considerado apenas enquanto a conta não tiver autenticador MFA, e ignorado assim que o TOTP ou uma credencial WebAuthn existir ² Necessário quando a conta tiver algum autenticador MFA, a menos que um token sudo válido já esteja presente ³ Necessário quando mfa_method for totp, com um código de autenticador atual ou um código de backup não consumido ⁴ Ambos os campos são necessários juntos quando mfa_method for webauthn

Objeto de códigos de backup MFA

Estrutura

Campo	Tipo	Descrição
backup_codes	array[objeto de código de backup MFA]	Os códigos de backup atuais da conta

Exemplo

{
  "backup_codes": [
    {"code": "a3f2-9kd7", "consumed": false},
    {"code": "b81c-4nq0", "consumed": true}
  ]
}

Objeto de código de backup MFA

Um código de backup é formado por dois grupos de quatro caracteres separados por um hífen. Cada grupo é extraído do alfabeto latino minúsculo e dos dígitos decimais.

Estrutura

Campo	Tipo	Descrição
code	string	Código de backup de uso único
consumed	boolean	Se o código já foi consumido

Objeto de desafio de códigos de backup MFA

O estado de um ticket de desafio de códigos de backup recém-criado.

Estrutura

Campo	Tipo	Descrição
ticket	string	O identificador que todas as etapas posteriores deste fluxo enviam
code_expires_at	timestamp ISO8601	O momento em que o código enviado por email expira, 10 minutos após ter sido enviado
resend_available_at	timestamp ISO8601	O primeiro momento em que o código pode ser reenviado, 30 segundos após o último envio

Objeto de verificação de códigos de backup MFA

Os códigos de backup e a prova que um desafio verificado retorna.

Estrutura

Campo	Tipo	Descrição
backup_codes	array[objeto de código de backup MFA]	Os códigos de backup atuais da conta
verification_proof1	string	A prova que Regenerar códigos de backup MFA consome

¹ Um reenvio limpa a prova armazenada e a próxima verificação emite um valor diferente

Objeto de credencial WebAuthn

Uma conta possui no máximo 10 credenciais WebAuthn. Tanto Criar opções de registro WebAuthn quanto Registrar credencial WebAuthn aplicam esse limite.

O Decoding Chat verifica cada asserção contra o identificador da parte confiável e as origens permitidas configuradas para a instância. O Decoding Chat rejeita uma asserção cujo contador de assinatura relatado não seja maior que o contador armazenado. A exceção é um contador armazenado e um relatado iguais a zero, que é como um autenticador sem contador aparece.

Estrutura

Campo	Tipo	Descrição
id	string	ID da credencial em Base64url
name	string	Nome da credencial atribuído pelo usuário (1-100 caracteres)
created_at	timestamp ISO8601	O tempo que Registrar credencial WebAuthn armazenou a credencial
last_used_at1	?timestamp ISO8601	Autenticação bem-sucedida mais recente

¹ Nulo até que a credencial conclua um login, MFA ou asserção sudo pela primeira vez

O Decoding Chat nunca retorna a chave pública da credencial, o contador de assinaturas ou os transportes relatados.

Objeto de descritor de credencial WebAuthn

Estrutura

Campo	Tipo	Descrição
id	string	ID da credencial em Base64url
type	string	Tipo de credencial, sempre public-key
transports?1	array[string]	Transportes de autenticador a partir dos valores de transporte do autenticador WebAuthn

¹ Presente apenas quando o autenticador relatou seus transportes durante o registro

Transportes do autenticador WebAuthn

Valor	Descrição
ble	Bluetooth Low Energy
cable	Cloud-assisted Bluetooth Low Energy
hybrid	Transporte híbrido
internal	Autenticador de plataforma
nfc	Near-field communication
smart-card	Cartão inteligente
usb	Autenticador USB

Objeto de asserção WebAuthn

A serialização PublicKeyCredential do WebAuthn no navegador. Os nomes dos campos estão em camelCase, porque o Decoding Chat aceita a estrutura exata que a API cliente do WebAuthn produz.

Estrutura

Campo	Tipo	Descrição
id	string	ID da credencial em Base64url
rawId	string	ID bruto da credencial em Base64url
response	objeto de resposta de asserção WebAuthn	Resposta de asserção do autenticador
authenticatorAttachment?	string	Anexo do autenticador, cross-platform ou platform
clientExtensionResults	objeto de resultados de extensão de cliente WebAuthn	Saídas da extensão do cliente
type	string	Tipo de credencial, sempre public-key

Campos malformados retornam INVALID_FORM_BODY. Cada operação documenta seus erros de verificação criptográfica.

Objeto de resposta de asserção WebAuthn

Estrutura

Campo	Tipo	Descrição
clientDataJSON	string	JSON de dados do cliente em Base64url
authenticatorData	string	Dados do autenticador em Base64url
signature	string	Assinatura da asserção em Base64url
userHandle?1	string	Identificador de usuário em Base64url

¹ Presente apenas quando a asserção veio de uma credencial descobrível

Objeto de resposta de registro WebAuthn

Estrutura

Campo	Tipo	Descrição
id	string	ID da credencial em Base64url
rawId	string	ID bruto da credencial em Base64url
response	objeto de resposta de atestado WebAuthn	Resposta de atestado do autenticador
authenticatorAttachment?	string	Anexo do autenticador, cross-platform ou platform
clientExtensionResults	objeto de resultados de extensão de cliente WebAuthn	Saídas da extensão do cliente
type	string	Tipo de credencial, sempre public-key

Campos malformados retornam INVALID_FORM_BODY. Um atestado que falha na verificação retorna INVALID_WEBAUTHN_CREDENTIAL.

Objeto de resposta de atestado WebAuthn

Estrutura

Campo	Tipo	Descrição
clientDataJSON	string	JSON de dados do cliente em Base64url
attestationObject	string	Objeto de atestado em Base64url
authenticatorData?	string	Dados do autenticador em Base64url
transports?1	array[string]	Transportes de autenticador a partir dos valores de transporte do autenticador WebAuthn
publicKeyAlgorithm?	integer	Identificador do algoritmo de chave pública COSE
publicKey?	string	Chave pública da credencial em Base64url

¹ Retido com a credencial e retornado posteriormente em allowCredentials e excludeCredentials

Objeto de resultados de extensão de cliente WebAuthn

Estrutura

Campo	Tipo	Descrição
appid?	boolean	Se a extensão AppID foi usada
credProps?	objeto de propriedades de credencial WebAuthn	Saída de propriedades de credencial
hmacCreateSecret?	boolean	Se o autenticador criou um segredo HMAC

O Decoding Chat aceita campos adicionais de resultados de extensão.

Objeto de propriedades de credencial WebAuthn

Estrutura

Campo	Tipo	Descrição
rk?	boolean	Se a credencial criada é descobrível

O Decoding Chat aceita campos adicionais de propriedade de credencial.

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

Cada operação que emite um desafio de autenticação WebAuthn retorna este objeto: a verificação sudo aqui e as operações de opção de login na autenticação HTTP.

Estrutura

Campo	Tipo	Descrição
challenge1	string	Desafio de uso único em Base64url
timeout2	integer	Tempo limite de operação do autenticador em milissegundos
rpId	string	Identificador da parte confiável configurado para a instância
allowCredentials?3	array[objeto de descritor de credencial WebAuthn]	Credenciais aceitas para esta operação
userVerification4	string	Requisito de verificação de usuário, sendo um entre discouraged, preferred ou required

¹ Expira cinco minutos após a emissão e está vinculado à operação que o emitiu, de modo que um desafio sudo não pode ser resgatado como uma asserção de login ² Cada operação emite o valor fixo 60000, uma opção de requisição padrão para PublicKeyCredential ³ As opções sudo listam cada credencial registrada na conta. O campo está ausente apenas na rota de login descobrível ⁴ Opções sudo e a conclusão de login MFA solicitam discouraged. O login descobrível solicita e verifica required

O Decoding Chat não emite nenhum outro membro de opções de requisição PublicKeyCredential, então hints e extensions nunca aparecem neste objeto.

Objeto de opções de registro WebAuthn

Estrutura

Campo	Tipo	Descrição
rp	objeto de parte confiável WebAuthn	Identidade da parte confiável
user	objeto de usuário de registro WebAuthn	Identidade da conta vinculada à credencial
challenge	string	Desafio de uso único em Base64url
pubKeyCredParams1	array[objeto de parâmetro de chave pública WebAuthn]	Algoritmos de chave pública aceitos
timeout2	integer	Tempo limite de operação do autenticador em milissegundos
excludeCredentials3	array[objeto de descritor de credencial WebAuthn]	Credenciais existentes que não podem ser registradas novamente
authenticatorSelection4	objeto de seleção de autenticador WebAuthn	Requisitos de seleção de autenticador
attestation5	string	Transmissão de atestado, sempre none
extensions6	objeto de entradas de extensão de cliente WebAuthn	Extensões de cliente solicitadas
hints7	array[string]	Dicas de autenticador

¹ Sempre os identificadores COSE -8, -7 e -257, nessa ordem, significando EdDSA, ECDSA com SHA-256 e RSASSA-PKCS1-v1_5 com SHA-256 ² Cada registro emite o valor fixo 60000 ³ Contém todas as credenciais já registradas na conta, para que um autenticador não possa inscrever a mesma credencial duas vezes. É um array vazio quando a conta não possui nenhuma ⁴ O Decoding Chat solicita uma credencial descobrível preferencial e uma verificação de usuário preferencial, e não exige nenhuma das duas, então requireResidentKey é false ⁵ O Decoding Chat solicita none, então nenhuma declaração de atestado é retida ⁶ Sempre presente com credProps definido como true, a única extensão que o Decoding Chat solicita ⁷ Sempre um array vazio

Objeto de parte confiável WebAuthn

Estrutura

Campo	Tipo	Descrição
name	string	Nome de exibição da parte confiável configurado para a instância
id	string	Identificador da parte confiável configurado para a instância

Objeto de usuário de registro WebAuthn

Estrutura

Campo	Tipo	Descrição
id	string	Identificador do usuário WebAuthn, o snowflake da conta decimal codificado como base64url
name	string	Nome de usuário da conta
displayName1	string	Rótulo de exibição da conta

¹ O Decoding Chat fornece o nome de usuário da conta tanto em name quanto em displayName

Objeto de parâmetro de chave pública WebAuthn

Estrutura

Campo	Tipo	Descrição
alg	integer	Identificador do algoritmo COSE
type	string	Tipo de credencial, sempre public-key

Objeto de seleção de autenticador WebAuthn

Estrutura

Campo	Tipo	Descrição
authenticatorAttachment?	string	Anexo do autenticador, cross-platform ou platform
requireResidentKey?	boolean	Se uma credencial descobrível é necessária
residentKey?	string	Preferência de credencial descobrível, sendo um entre discouraged, preferred ou required
userVerification?	string	Preferência de verificação de usuário, sendo um entre discouraged, preferred ou required

Objeto de entradas de extensão de cliente WebAuthn

Estrutura

Campo	Tipo	Descrição
appid?	string	Valor da extensão AppID
credProps?1	boolean	Se as propriedades da credencial são solicitadas
hmacCreateSecret?	boolean	Se a criação de segredo HMAC é solicitada
minPinLength?	boolean	Se o comprimento mínimo do PIN é solicitado

¹ O único membro que o Decoding Chat sempre define, sempre true nas opções de registro WebAuthn

Objeto de métodos MFA sudo

Estrutura

Campo	Tipo	Descrição
totp	boolean	Se a conta tem um segredo TOTP e o tipo de autenticador TOTP, conforme o objeto de disponibilidade de método do modo sudo
webauthn	boolean	Se a conta tem o tipo de autenticador WebAuthn
has_mfa	boolean	Se a conta tem o tipo de autenticador TOTP ou WebAuthn, conforme o objeto de métodos do modo sudo

Ativar MFA TOTP

POST/v1/users/@me/mfa/totp/enableMFA

Ativa o TOTP para a conta atual e retorna um objeto de códigos de backup MFA contendo 10 novos códigos. O modo sudo é obrigatório. Emite um evento de Gateway Atualização de Usuário.

O Decoding Chat verifica o modo sudo primeiro, então uma conta que já possui uma credencial WebAuthn prova isso com essa credencial.

Limitações

• A conta precisa de um endereço de email verificado ou é recusada com 403 MFA_EMAIL_VERIFICATION_REQUIRED.
• Uma conta que já possui o TOTP ativado é recusada com 400 TWO_FA_NOT_ENABLED.

Corpo JSON

O corpo estende o objeto de verificação sudo com os campos abaixo, e uma prova sudo existente é enviada no cabeçalho de requisição X-Fluxer-Sudo-Mode-JWT.

Campo	Tipo	Descrição
secret1	string	Segredo TOTP em Base32 (1-256 caracteres)
code2	string	Código TOTP atual gerado a partir do segredo enviado (1-32 caracteres)

¹ Gerado pelo cliente e armazenado literalmente (verbatim) na conta ² Um código de backup é rejeitado aqui

Resposta

Status	Corpo	Condição
200	objeto de códigos de backup MFA	O TOTP foi ativado e 10 códigos de backup foram emitidos
400	resposta de erro	O código TOTP não correspondeu ao segredo enviado, retornando INVALID_CODE no caminho code, ou o TOTP já está ativado e a requisição retorna TWO_FA_NOT_ENABLED
403	resposta de erro	O email da conta não está verificado e a requisição retorna MFA_EMAIL_VERIFICATION_REQUIRED, ou o modo sudo não foi provado e a requisição retorna SUDO_MODE_REQUIRED

Efeitos colaterais

O TOTP é ativado e 10 códigos de backup são emitidos. Qualquer código de backup que a conta já possuía permanece no lugar, então a resposta tem apenas os 10 novos códigos. O Decoding Chat também copia os tipos de autenticador da conta para cada conta de bot que o usuário possui. A Atualização de Usuário chega às sessões do usuário e a cada bot possuído cujos tipos de autenticador mudaram.

Limite de taxa

10 requisições por minuto para cada usuário autenticado, no bucket user:mfa:totp:enable.

Desativar MFA TOTP

POST/v1/users/@me/mfa/totp/disableMFA

Desativa o TOTP para a conta atual e retorna 204 com o corpo vazio. O modo sudo é obrigatório. Emite um evento de Gateway Atualização de Usuário.

O Decoding Chat verifica um código de autenticador ou código de backup para cada requisição. Com um token sudo válido, ele verifica code. Sem um, os campos de verificação sudo provam o modo sudo quando mfa_method está definido, e o Decoding Chat não verifica code. Caso contrário, code prova o modo sudo como se fosse mfa_code com mfa_method definido como totp, para que a tentativa consuma a permissão TOTP descrita em modo sudo.

O TOTP já deve estar ativado, ou a requisição é recusada com 400 TWO_FACTOR_REQUIRED. Um email verificado não é obrigatório, portanto uma conta cujo endereço se tornou não verificado posteriormente ainda pode remover seu autenticador.

Corpo JSON

O corpo estende o objeto de verificação sudo com o campo abaixo, e uma prova sudo existente é enviada no cabeçalho de requisição X-Fluxer-Sudo-Mode-JWT.

Campo	Tipo	Descrição
code1	string	Código TOTP atual ou um código de backup não consumido (1-32 caracteres)

¹ Um valor errado retorna INVALID_CODE no caminho code com um token sudo, e INVALID_MFA_CODE no caminho mfa_code quando code prova o modo sudo

Códigos de backup não sobrevivem à remoção do TOTP

Desativar o TOTP invalida todos os códigos de backup da conta, incluindo o código que provou esta requisição. Uma conta que mantém uma credencial WebAuthn fica sem nenhum código e precisa de Listar códigos de backup MFA com regenerate definido como true para emitir um novo conjunto.

Resposta

Status	Corpo	Condição
204	vazio	O TOTP foi desativado
400	resposta de erro	O código não correspondeu, ou o TOTP não está ativado e a requisição retorna TWO_FACTOR_REQUIRED
403	resposta de erro	O modo sudo não foi provado e a requisição retorna SUDO_MODE_REQUIRED

Efeitos colaterais

O TOTP é desativado e todos os códigos de backup param de funcionar. O Decoding Chat remove o tipo de autenticador TOTP, juntamente com o valor legado não atribuído de autenticador 1 caso a conta ainda o mantenha. O Decoding Chat também copia os tipos de autenticador da conta para cada conta de bot que o usuário possui. A Atualização de Usuário vai para as sessões do usuário e a cada bot possuído cujos tipos de autenticador mudaram.

Limite de taxa

10 requisições por minuto para cada usuário autenticado, no bucket user:mfa:totp:disable.

Listar códigos de backup MFA

POST/v1/users/@me/mfa/backup-codesMFA

Retorna um objeto de códigos de backup MFA, substituindo primeiro o conjunto quando regenerate for verdadeiro (true). O modo sudo é obrigatório.

Nem um email verificado nem um autenticador são necessários, de modo que uma conta sem nenhum MFA pode provar o modo sudo com sua senha e usar esta operação.

Um código de backup enviado como mfa_code para satisfazer o modo sudo é consumido. Com regenerate falso, ele retorna com consumed definido como verdadeiro. Com regenerate verdadeiro, ele é excluído junto com o resto do conjunto anterior e não aparece.

A regeneração substitui o conjunto anterior imediatamente

Todos os códigos anteriores tornam-se inválidos. Se a regeneração falhar, os códigos antigos já podem estar inutilizáveis.

Corpo JSON

O corpo estende o objeto de verificação sudo com o campo abaixo, e uma prova sudo existente é enviada no cabeçalho de requisição X-Fluxer-Sudo-Mode-JWT.

Campo	Tipo	Descrição
regenerate1	boolean	Se o conjunto atual deve ser descartado e emitir 10 substitutos

¹ O campo é obrigatório. Passar false lê o conjunto atual sem alterá-lo

Resposta

Status	Corpo	Condição
200	objeto de códigos de backup MFA	Os códigos atuais ou substitutos foram retornados
403	resposta de erro	O modo sudo não foi provado e a requisição retorna SUDO_MODE_REQUIRED

Limite de taxa

6 requisições por minuto para cada usuário autenticado, no bucket user:mfa:backup_codes.

Iniciar desafio de códigos de backup MFA

POST/v1/users/@me/mfa/backup-codes/challenge

Cria um ticket de desafio de códigos de backup e envia um código de verificação para o endereço de email da conta. Retorna um objeto de desafio de códigos de backup MFA em caso de sucesso.

O modo sudo não é obrigatório, e a rota não lê nenhum campo de verificação sudo.

O envio consome o controle de início do desafio.

Limitações

• A conta precisa de um endereço de email verificado e é recusada de outra forma com 403 MFA_EMAIL_VERIFICATION_REQUIRED.
• Uma conta que não possui nenhum endereço de email é recusada com 400 INVALID_FORM_BODY e o código de validação USER_DOES_NOT_HAVE_AN_EMAIL_ADDRESS no caminho email.
• A conta precisa do TOTP ativado e é recusada de outra forma com 400 TWO_FACTOR_REQUIRED.

Corpo JSON

O corpo pode ser omitido, e qualquer corpo fornecido é um objeto sem campos. O Decoding Chat remove chaves desconhecidas antes de processar a requisição.

Resposta

Status	Corpo	Condição
200	objeto de desafio de códigos de backup MFA	O ticket foi criado e um código foi enviado
400	resposta de erro	O TOTP não está ativado e a requisição retorna TWO_FACTOR_REQUIRED, ou a conta não possui nenhum endereço
403	resposta de erro	O email da conta não está verificado e a requisição retorna MFA_EMAIL_VERIFICATION_REQUIRED

Efeitos colaterais

O Decoding Chat armazena um ticket contendo o código e sua data de validade, e um email de verificação é enviado para o endereço da conta. Nenhum campo da conta é alterado e nenhum código de backup é emitido.

Limite de taxa

6 requisições por minuto para cada usuário autenticado, no bucket user:mfa:backup_codes_challenge:start.

Reenviar código de desafio de códigos de backup MFA

POST/v1/users/@me/mfa/backup-codes/challenge/resend

Envia um novo código de verificação para um ticket ativo de desafio de códigos de backup. Retorna 204 com o corpo vazio.

A rota lê apenas o ticket e o endereço da conta. Uma conta que não possui nenhum endereço de email é recusada com 400 INVALID_FORM_BODY e o código de validação USER_DOES_NOT_HAVE_AN_EMAIL_ADDRESS no caminho email.

O envio consome o controle de reenvio do desafio, e o ticket impõe seu próprio tempo de espera (cooldown) de 30 segundos.

Um reenvio desfaz uma verificação concluída

O Decoding Chat limpa a prova armazenada no ticket a cada reenvio. Um cliente que já possui uma prova precisa de Verificar código de desafio de códigos de backup MFA novamente antes que Regenerar códigos de backup MFA o aceite.

Corpo JSON

Campo	Tipo	Descrição
ticket	string	O identificador retornado por Iniciar desafio de códigos de backup MFA (1-256 caracteres)

Resposta

Status	Corpo	Condição
204	vazio	Um código substituto foi enviado
400	resposta de erro	O ticket é desconhecido e a requisição retorna INVALID_OR_EXPIRED_TICKET

Efeitos colaterais

O Decoding Chat substitui o código do ticket, o tempo de envio e o tempo de expiração do código, o que invalida o código anterior. A prova armazenada é limpa e um email de verificação vai para o endereço da conta.

Limite de taxa

6 requisições por minuto para cada usuário autenticado, no bucket user:mfa:backup_codes_challenge:resend.

Verificar código de desafio de códigos de backup MFA

POST/v1/users/@me/mfa/backup-codes/challenge/verify

Verifica o código enviado por email e retorna um objeto de verificação de códigos de backup MFA contendo os códigos atuais e uma prova.

A verificação consome o código. Um ticket que não contém código falha com VERIFICATION_CODE_NOT_ISSUED, que é o que uma segunda verificação do mesmo ticket retorna. Um código além de seu tempo de vida de 10 minutos falha com VERIFICATION_CODE_EXPIRED. Uma incompatibilidade falha com INVALID_VERIFICATION_CODE.

O Decoding Chat cobra a permissão de verificação por ticket antes de ler o código, de forma que tanto um código incorreto quanto um código correto consomem dessa permissão.

Corpo JSON

Campo	Tipo	Descrição
ticket	string	O identificador retornado por Iniciar desafio de códigos de backup MFA (1-256 caracteres)
code	string	O código enviado ao endereço da conta (1-256 caracteres)

Resposta

Status	Corpo	Condição
200	objeto de verificação de códigos de backup MFA	O código foi aceito
400	resposta de erro	O ticket retorna INVALID_OR_EXPIRED_TICKET, ou o código não foi emitido, expirou ou não correspondeu

Efeitos colaterais

O ticket armazena uma nova prova e seu código é limpo. A resposta contém todos os códigos de backup da conta, incluindo os consumidos. Nenhum código de backup é emitido, consumido ou excluído.

Limite de taxa

20 requisições por minuto para cada usuário autenticado, no bucket user:mfa:backup_codes_challenge:verify.

Regenerar códigos de backup MFA

POST/v1/users/@me/mfa/backup-codes/challenge/regenerate

Substitui os códigos de backup da conta por 10 novos e retorna um objeto de códigos de backup MFA. O modo sudo não é obrigatório.

O ticket e sua prova são a única autorização. Sem o TOTP ativado, a requisição é recusada com 400 TWO_FACTOR_REQUIRED.

Um ticket sem nenhuma prova retorna INVALID_OR_EXPIRED_TICKET no caminho verification_proof, e uma prova que não corresponde retorna INVALID_PROOF_TOKEN.

A regeneração deixa o ticket utilizável

O mesmo ticket e prova podem substituir o conjunto novamente até que o ticket expire, 30 minutos após a verificação.

Corpo JSON

Campo	Tipo	Descrição
ticket	string	O identificador retornado por Iniciar desafio de códigos de backup MFA (1-256 caracteres)
verification_proof	string	A prova emitida por Verificar código de desafio de códigos de backup MFA (1-256 caracteres)

Resposta

Status	Corpo	Condição
200	objeto de códigos de backup MFA	O conjunto anterior foi excluído e 10 substitutos foram emitidos
400	resposta de erro	O TOTP não está ativado e a requisição retorna TWO_FACTOR_REQUIRED, ou o ticket ou a prova foi rejeitado

Efeitos colaterais

O conjunto anterior é substituído por 10 novos códigos. Uma falha pode deixar os códigos antigos inutilizáveis. Os tipos de autenticador permanecem inalterados e nenhum evento do Gateway é emitido.

Limite de taxa

6 requisições por minuto para cada usuário autenticado, no bucket user:mfa:backup_codes_challenge:regenerate.

Listar credenciais WebAuthn

GET/v1/users/@me/mfa/webauthn/credentials

Retorna um array de objetos de credencial WebAuthn registrados para a conta atual, ou um array vazio quando não houver nenhum. O modo sudo não é obrigatório.

Resposta

Status	Corpo	Condição
200	array[objeto de credencial WebAuthn]	As credenciais foram retornadas

Limite de taxa

40 requisições a cada 10 segundos para cada usuário autenticado, no bucket mfa:webauthn:list.

Criar opções de registro WebAuthn

POST/v1/users/@me/mfa/webauthn/credentials/registration-optionsMFA

Cria um desafio de registro de uso único e retorna um objeto de opções de registro WebAuthn. O modo sudo é obrigatório.

Esta operação não define o cabeçalho de resposta X-Fluxer-Sudo-Mode-JWT.

Limitações

• A conta precisa de um endereço de email verificado.
• Uma conta que já possui 10 credenciais recebe 400 WEBAUTHN_CREDENTIAL_LIMIT_REACHED e nenhum desafio.

Corpo JSON

O corpo é um objeto de verificação sudo. Uma prova sudo existente é enviada no cabeçalho de requisição X-Fluxer-Sudo-Mode-JWT.

Resposta

Status	Corpo	Condição
200	objeto de opções de registro WebAuthn	O desafio e as opções de registro foram emitidos
400	resposta de erro	10 credenciais já estão registradas e a requisição retorna WEBAUTHN_CREDENTIAL_LIMIT_REACHED
403	resposta de erro	O email da conta não está verificado e a requisição retorna MFA_EMAIL_VERIFICATION_REQUIRED, ou o modo sudo não foi provado e a requisição retorna SUDO_MODE_REQUIRED

Efeitos colaterais

O Decoding Chat emite um desafio de registro para o usuário atual. Ele expira após cinco minutos e pode ser resgatado uma vez.

Limite de taxa

20 requisições a cada 10 segundos para cada usuário autenticado, no bucket mfa:webauthn:registration_options.

Registrar credencial WebAuthn

POST/v1/users/@me/mfa/webauthn/credentials

Consome um desafio de registro, adiciona uma credencial WebAuthn à conta atual e retorna 204 com o corpo vazio. Emite um evento de Gateway Atualização de Credenciais WebAuthn, e um evento de Atualização de Usuário quando esta é a primeira credencial WebAuthn da conta.

A conta precisa de um email verificado e ter menos de 10 credenciais registradas. Esta rota não aceita nenhum campo de verificação sudo próprio. O Decoding Chat verifica o atestado em relação ao identificador da parte confiável da instância e suas origens permitidas, e não exige verificação de usuário.

Corpo JSON

Campo	Tipo	Descrição
response	objeto de resposta de registro WebAuthn	Resposta do autenticador para o desafio de registro
challenge	string	Desafio de registro de uso único (1-1024 caracteres)
name	string	Nome da credencial atribuído pelo usuário (1-100 caracteres)

Um registro falho não pode reutilizar seu desafio

O Decoding Chat consome o desafio de registro antes de verificar novamente o limite de credenciais e antes de verificar o atestado. Solicite opções de registro novas após qualquer falha.

Resposta

Status	Corpo	Condição
204	vazio	A credencial foi registrada
400	resposta de erro	O desafio ou o atestado falhou e a requisição retorna INVALID_WEBAUTHN_CREDENTIAL, a chave pública retorna INVALID_WEBAUTHN_PUBLIC_KEY_FORMAT, o contador de assinaturas retorna INVALID_WEBAUTHN_CREDENTIAL_COUNTER ou o limite retorna WEBAUTHN_CREDENTIAL_LIMIT_REACHED
403	resposta de erro	O email da conta não está verificado e a requisição retorna MFA_EMAIL_VERIFICATION_REQUIRED

Efeitos colaterais

A credencial é adicionada à conta. Quando for a primeira credencial WebAuthn da conta, o Decoding Chat também copia os tipos de autenticador da conta, que agora incluem WebAuthn, para cada conta de bot que o usuário possui.

A Atualização de Credenciais WebAuthn chega às sessões do usuário com os resumos completos das credenciais atuais. Quando os tipos de autenticador mudam, a Atualização de Usuário também chega ao usuário e a cada bot possuído afetado.

Limite de taxa

10 requisições por minuto para cada usuário autenticado, no bucket mfa:webauthn:register.

Renomear credencial WebAuthn

PATCH/v1/users/@me/mfa/webauthn/credentials/{credential_id}MFA

Altera o nome atribuído pelo usuário de uma credencial WebAuthn pertencente à conta atual e retorna 204 com o corpo vazio. O modo sudo é obrigatório. Emite um evento de Gateway Atualização de Credenciais WebAuthn.

Um email verificado não é obrigatório.

Parâmetros de caminho

Campo	Tipo	Descrição
credential_id	string	ID da credencial em Base64url registrada para a conta atual (1-2048 caracteres)

Corpo JSON

O corpo estende o objeto de verificação sudo com o campo abaixo, e uma prova sudo existente é enviada no cabeçalho de requisição X-Fluxer-Sudo-Mode-JWT.

Campo	Tipo	Descrição
name	string	Nome de credencial substituto (1-100 caracteres)

Resposta

Status	Corpo	Condição
204	vazio	A credencial foi renomeada
403	resposta de erro	O modo sudo não foi provado e a requisição retorna SUDO_MODE_REQUIRED
404	resposta de erro	A credencial não está registrada na conta atual, retornando UNKNOWN_WEBAUTHN_CREDENTIAL

Efeitos colaterais

O nome da credencial é substituído e nenhum tipo de autenticador é alterado. A Atualização de Credenciais WebAuthn chega às sessões do usuário atual com os resumos completos das credenciais atuais.

Limite de taxa

20 requisições a cada 10 segundos para cada usuário autenticado, no bucket mfa:webauthn:update.

Excluir credencial WebAuthn

DELETE/v1/users/@me/mfa/webauthn/credentials/{credential_id}MFA

Exclui uma credencial WebAuthn pertencente à conta atual e retorna 204 com o corpo vazio. O modo sudo é obrigatório. Emite um evento de Gateway Atualização de Credenciais WebAuthn, e um evento de Atualização de Usuário quando esta era a última credencial WebAuthn da conta.

Um email verificado não é obrigatório.

Parâmetros de caminho

Campo	Tipo	Descrição
credential_id	string	ID da credencial em Base64url registrada para a conta atual (1-2048 caracteres)

Corpo JSON

O corpo é um objeto de verificação sudo. Uma prova sudo existente é enviada no cabeçalho de requisição X-Fluxer-Sudo-Mode-JWT.

Remover a credencial final remove um autenticador

Excluir a última credencial WebAuthn da conta remove o tipo de autenticador WebAuthn. Sem o TOTP, a conta então não tem nenhum autenticador MFA, e o modo sudo recorre à senha da conta.

Resposta

Status	Corpo	Condição
204	vazio	A credencial foi excluída
403	resposta de erro	O modo sudo não foi provado e a requisição retorna SUDO_MODE_REQUIRED
404	resposta de erro	A credencial não está registrada na conta atual, retornando UNKNOWN_WEBAUTHN_CREDENTIAL

Efeitos colaterais

A credencial é excluída. Quando era a final, o tipo de autenticador WebAuthn também é removido de cada conta de bot que o usuário possui.

A Atualização de Credenciais WebAuthn chega às sessões do usuário com os resumos das credenciais restantes. Quando os tipos de autenticador mudam, a Atualização de Usuário também chega ao usuário e a cada bot possuído afetado.

Limite de taxa

10 requisições por minuto para cada usuário autenticado, no bucket mfa:webauthn:delete.

Obter métodos MFA sudo

GET/v1/users/@me/sudo/mfa-methods

Retorna um objeto de métodos MFA sudo descrevendo quais desafios sudo a conta atual pode responder. O modo sudo não é obrigatório.

Resposta

Status	Corpo	Condição
200	objeto de métodos MFA sudo	Os métodos disponíveis foram retornados

Limite de taxa

20 requisições por minuto para cada usuário autenticado, no bucket sudo:mfa:methods.

Criar opções de autenticação sudo WebAuthn

POST/v1/users/@me/sudo/webauthn/authentication-options

Cria um desafio sudo de uso único e retorna um objeto de opções de autenticação WebAuthn listando todas as credenciais registradas na conta atual.

A conta precisa de pelo menos uma credencial WebAuthn registrada. O modo sudo não é obrigatório para obter o desafio.

Resposta

Status	Corpo	Condição
200	objeto de opções de autenticação WebAuthn	O desafio e as opções foram emitidos
400	resposta de erro	Nenhuma credencial WebAuthn está registrada e a requisição retorna NO_PASSKEYS_REGISTERED

Efeitos colaterais

O Decoding Chat emite um desafio sudo para o usuário atual. Ele expira após cinco minutos e pode ser resgatado uma vez ao enviá-lo como webauthn_challenge ao lado de webauthn_response em um objeto de verificação sudo.

Limite de taxa

10 requisições por minuto para cada usuário autenticado, no bucket sudo:webauthn:options.