Autenticação

Envie uma credencial no cabeçalho Authorization. Cada operação indica quais tipos de credencial aceita.

As falhas usam a resposta de erro padrão. A API HTTP de autenticação e a API HTTP de OAuth2 documentam a emissão e a revogação de credenciais.

Manuseio de credenciais

Quem tiver uma credencial pode agir como o dono dela. Mantenha credenciais fora de logs, ferramentas de análise, relatórios de falha e código-fonte, e guarde-as apenas pelo tempo necessário. Use TLS em redes não confiáveis.

Nunca coloque uma credencial Authorization em uma URL. No caso de tokens de webhook, caminhos de mídia assinados e capacidades de upload, trate a URL completa como segredo. Não a exponha por redirecionamentos, rastreamentos ou referenciadores.

Cabeçalho Authorization

Use uma das formas abaixo, com um token não vazio e sem espaços ao redor. Os prefixos de esquema diferenciam maiúsculas de minúsculas, exceto nas duas rotas indicadas em Tokens de bot.

Esquemas de autorização

Valor	Nome	Descrição
`Bot <token>`	Token de bot	Autentica a conta de bot da aplicação
`Bearer <token>`	Token de acesso OAuth2¹	Acesso concedido por uma conta, limitado aos escopos do token
`<token>`	Token de sessão de usuário	Enviado sem prefixo de esquema
`Admin <token>`	Chave da API de administração	Aceita apenas abaixo de `/v1/admin`, com permissões limitadas pela chave e por seu dono

¹ Um valor é tratado de forma diferente. Bearer flx_ seguido de 36 caracteres alfanuméricos autentica a sessão de usuário que ele nomeia

Formatos de token

Trate os tokens emitidos como valores opacos. Envie-os sem alteração, com o esquema apropriado. Um token de bot inclui o ID da aplicação e o segredo no formato <application_id>.<secret>.

Tokens de sessão de usuário

Um token de sessão de usuário autentica uma conta de usuário comum. O login, o registro e a troca de sessão na API HTTP de autenticação o emitem. O Gateway o aceita em Identify.

Uma prova de modo sudo complementa o token por meio do cabeçalho separado X-Fluxer-Sudo-Mode-JWT.

Tokens de bot

O Gateway aceita um token de bot em Identify. As operações HTTP GET /v1/gateway/bot e GET /v1/applications/@me aceitam prefixos de esquema sem diferenciar maiúsculas. GET /v1/applications/@me exige especificamente Bot e retorna 401 INVALID_TOKEN para qualquer outra coisa. A seção Autenticação no Gateway trata de GET /v1/gateway/bot.

Um bot não pode usar uma operação restrita a contas de usuário comuns, e tal operação retorna 403 ACCESS_DENIED. Uma operação em Autenticação que resolve uma conta a partir do corpo da requisição ou do token, como login, recuperação de senha, verificação de e-mail, reversão de e-mail e autorização de IP, retorna 403 BOT_USER_AUTH_ENDPOINT_ACCESS_DENIED quando essa conta é um bot.

Tokens de acesso OAuth2

Todo token de acesso OAuth2 pertence a uma conta. As concessões suportadas são código de autorização e token de atualização. Veja os esquemas de autorização para a sintaxe Bearer e a exceção de sessão de usuário.

Apenas operações que declaram suporte a OAuth2 aceitam tokens de acesso. Uma operação de usuário sem esse suporte retorna 403 ACCESS_DENIED mesmo para um token de acesso válido.

Uma operação que aceita tanto token de sessão de usuário quanto token de acesso OAuth2 verifica o escopo somente no token de acesso. Uma operação exclusiva de bearer rejeita token de sessão, token de bot ou chave da API de administração com 401 UNAUTHORIZED.

Um escopo ausente retorna 403 MISSING_OAUTH_SCOPE. Cada operação exige exatamente o escopo que nomeia. A API HTTP de OAuth2 define os escopos suportados, as concessões, a atualização, a revogação e a introspecção.

Corpo de escopo OAuth2 ausente

O corpo da resposta traz este membro junto de code e message.

Campo	Tipo	Descrição
required_scope	string	O escopo OAuth2 que faltava na requisição

Chaves da API de administração

Uma chave da API de administração autentica como seu criador nas rotas abaixo de /v1/admin. As permissões são limitadas tanto pela chave quanto por quem a criou.

O Decoding Chat também aceita um token de sessão de usuário ou um token bearer OAuth2 em uma operação de administração, e aceita o token bearer apenas quando ele pertence à aplicação OAuth2 de administração embutida. Um token bearer de qualquer outra aplicação retorna 403 ACCESS_DENIED. Uma requisição com token de bot retorna 401 UNAUTHORIZED.

Toda requisição de administração exige a ACL admin:authenticate do usuário ou o curinga, caso contrário retorna 403 MISSING_PERMISSIONS. Requisições autenticadas por chave também exigem as ACLs da operação tanto na chave quanto em seu dono, caso contrário retornam 403 MISSING_ACL. A API de administração define as ACLs e o contrato de auditoria.

Resultados de autorização

Cada operação protegida declara sua política de autenticação:

Uma operação de usuário exige um usuário resolvido e rejeita credencial bearer OAuth2 para a qual não tenha optado. Uma operação exclusiva de usuário também rejeita conta de bot.
Uma operação de bot aceita token de bot, que resolve a conta de bot da aplicação como identidade da requisição.
Uma operação OAuth2 exige o esquema Bearer junto do escopo que ela nomeia.
Uma operação de administração exige credencial de sessão, bearer OAuth2 de administração ou chave da API de administração, junto das ACLs necessárias.

Apenas GET /v1/applications/@me exige o prefixo Bot em si.

Uma credencial pode afetar até uma operação não autenticada. Ela seleciona limites de taxa por conta e pode dispensar um CAPTCHA. Cada operação documenta qualquer outro uso da credencial.

Uma operação protegida retorna 401 UNAUTHORIZED para credencial ausente, malformada, desconhecida, expirada ou revogada. Tokens de bot em operações de administração e credenciais não bearer em operações exclusivas de bearer também retornam 401.

Uma identidade válida recusada pela operação retorna 403 ACCESS_DENIED. Uma operação de Autenticação que resolve uma conta de bot retorna 403 BOT_USER_AUTH_ENDPOINT_ACCESS_DENIED, como descrito em Tokens de bot.

Falhas de escopo e de permissão de administração usam os códigos específicos acima. Um 401 não traz cabeçalho WWW-Authenticate, então o cliente precisa inspecionar code.

Operações autenticadas comuns também aplicam as barreiras de estado da conta.

Imposição de logon único

Uma instância pode impor logon único depois que ele estiver configurado e habilitado. Enquanto a imposição estiver ativa, estas operações de autenticação retornam 403 SSO_REQUIRED:

O retorno de chamada do logon único devolve o mesmo código quando as reivindicações do provedor não correspondem a nenhuma conta existente e a instância não provisiona automaticamente.

A imposição vale apenas nessas operações, e não bloqueia troca de senha nem gerenciamento de múltiplos fatores em uma conta já autenticada. Habilitá-la mantém válidos os tokens de sessão, de bot, de acesso OAuth2 e as chaves da API de administração já emitidos.

Barreiras de estado da conta

Uma operação autenticada comum recusa uma conta com exigência pendente de atividade suspeita com 403 ACCOUNT_SUSPICIOUS_ACTIVITY. Cada sinalizador ativo na resposta é uma exigência que a conta ainda não cumpriu. O sinalizador deixa de aparecer na resposta assim que a conta cumpre aquela exigência.

Corpo de atividade suspeita na conta

Campo	Tipo	Descrição
data	object	Objeto cujo membro `suspicious_activity_flags` traz o bitfield de atividade suspeita ainda pendente

Uma rota que admite explicitamente uma conta com exigência pendente de atividade suspeita continua aceitando a credencial dela. Estas permanecem acessíveis enquanto houver exigência pendente:

Obter usuário atual e Modificar usuário atual.
Obter configurações do usuário atual.
O fluxo de troca de e-mail com suas variantes de endereço com devolução, e o reenvio da verificação de e-mail.
O fluxo de verificação de telefone.
Listagem e encerramento de sessões.
As operações de gerenciamento de aplicações e autorizações em Aplicações e OAuth2.

Uma operação de administração não aplica barreira de atividade suspeita.

Nenhuma barreira compartilhada recusa conta excluída ou desativada. Cada operação que lê o estado da conta aplica a própria regra, e as operações de login, senha e e-mail recusam de imediato uma conta excluída.

Falha de autenticação

Erros de autenticação não distinguem entre credencial desconhecida, expirada, revogada ou malformada. Veja os resultados de autorização para os códigos de resposta.

Falhas repetidas de autenticação podem resultar em banimento de IP. Pare de repetir uma credencial recusada e obtenha uma nova.

Modo sudo

O modo sudo é uma prova de curta duração de que o titular da conta reverificou uma credencial recentemente. Cada operação que o exige declara isso na própria página, e Autenticação multifator define as provas aceitas, os campos do objeto de verificação sudo e o objeto de métodos do modo sudo devolvido com 403 SUDO_MODE_REQUIRED.

Uma prova sudo dura cinco minutos. Apresente-a no cabeçalho de requisição X-Fluxer-Sudo-Mode-JWT. Um token inválido, expirado ou de outra conta produz a mesma resposta que um token ausente.

O Decoding Chat emite um token apenas para conta que possua um autenticador multifator, então uma conta só com senha precisa reverificar a cada operação que exija modo sudo. Criar opções de registro WebAuthn e Desativar conta atual não emitem token sudo e não retornam o cabeçalho de resposta X-Fluxer-Sudo-Mode-JWT, mesmo para conta com múltiplos fatores. Uma conta de bot satisfaz o modo sudo imediatamente. O mesmo vale para uma conta que não tenha nem senha nem autenticador multifator.

Autenticação no Gateway

Envie um token de bot ou token de sessão de usuário no comando Identify, não em um cabeçalho Authorization. Uma credencial inválida ou revogada encerra a conexão com o código 4004. Um token ausente encerra com 4002 e motivo Invalid identify payload.

O endpoint HTTP Obter informações do Gateway verifica apenas o formato do token de bot. Uma resposta bem-sucedida não prova que o token é válido.

Outras superfícies de credencial

Uma operação de execução de webhook traz o identificador e o token do webhook no caminho da requisição, e não aceita credencial Authorization. Webhooks define seu contrato.

A API do Proxy de mídia não lê o cabeçalho Authorization em uma rota comum de mídia ou de repasse. Um objeto armazenado é endereçado pelo caminho, mídia externa é autorizada pela assinatura do caminho, e uma requisição de repasse é autorizada pela capacidade embutida na URL. Repasse de upload define o contrato de capacidade.