Guia de Integração da API TOTP: 2FA com Aplicativo Autenticador para Aplicativos dos EUA (2026)

TOTP (Time-based One-Time Password) é o segundo fator que discretamente impulsiona a maioria das autenticações empresariais e de consumidores preocupados com segurança em 2026. Gerado no lado do cliente a partir de um segredo compartilhado, válido por 30 segundos, gratuito por uso, imune a ataques de SMS pumping e SS7. O porém: os usuários precisam instalar um aplicativo autenticador e concluir um registro único. Bem implementado, o TOTP é o segundo fator ideal para usuários recorrentes de alto volume e a evolução natural do SMS OTP. Este guia aborda a integração da API TOTP para aplicativos dos EUA em 2026, o padrão, as bibliotecas, a UX de registro e os padrões de produção.

O que é TOTP?

TOTP é um código de 6 a 8 dígitos gerado por um aplicativo autenticador (Google Authenticator, Authy, 1Password, Microsoft Authenticator) a partir de um segredo compartilhado que você configura no registro, válido por uma janela de 30 segundos. O código muda a cada 30 segundos. Tanto o aplicativo autenticador do usuário quanto o seu servidor calculam o mesmo código a partir do mesmo segredo, e a verificação os compara.

O padrão é RFC 6238, publicado em 2011 e estável desde então. Existem implementações em todas as principais linguagens. A verificação é gratuita por uso porque nenhuma mensagem é enviada; ambos os lados calculam o código localmente.

TOTP vs SMS OTP: Quando usar cada um

DimensãoSMS OTPTOTPConfiguração do usuárioNenhuma (todo usuário tem SMS)Registro único com leitura de código QR (~30 segundos)Tempo de verificação do usuárioLer SMS, inserir código (10-30 segundos)Abrir app, ler código, inserir (10-15 segundos)Custo por uso$0,01-0,04 nos EUA$0 (nenhuma mensagem enviada)Nível de segurança (NIST)"Restrito""Permitido"Vulnerável a SS7/troca de SIMSimNãoResistência a phishingVulnerável a engenharia socialLigeiramente melhor, mas não à prova de phishingFunciona offlineNão (precisa de SMS celular)Sim (códigos gerados localmente)Recuperação se o dispositivo for perdidoFácil (ainda tem o número de telefone)Requer códigos de recuperação pré-gerados no registroCobertura nos EUA~99% (universal)~30-40% dos usuários consumidores têm um aplicativo autenticador

Arquitetura ideal: SMS OTP no cadastro para cobertura universal, sugerir o registro de TOTP como um "upgrade" para usuários recorrentes, usar TOTP por padrão para usuários que se registraram. Nosso tutorial de 2FA aborda o padrão em camadas.

Integração TOTP: Como funciona

Três etapas de ponta a ponta:

Etapa 1: Gerar um Segredo no Registro

# Python com a biblioteca pyotp
import pyotp
secret = pyotp.random_base32()  # segredo codificado em base32 de 32 caracteres

# Armazene o segredo no registro do seu usuário (criptografado em repouso)
user.totp_secret = encrypt(secret)
user.save()



O segredo é a chave compartilhada. Tanto o seu servidor quanto o aplicativo autenticador do usuário precisam dele. Armazene-o criptografado em repouso no seu banco de dados de usuários.

Etapa 2: Criar o URI de Provisionamento e o Código QR

# Gerar o URI otpauth conforme RFC 6238
uri = pyotp.totp.TOTP(secret).provisioning_uri(
   name=user.email,
   issuer_name='YourApp'
)
# Formato: otpauth://totp/YourApp:user@example.com?secret=ABC...&issuer=YourApp

# Gerar um código QR que o usuário escaneia com seu aplicativo autenticador
import qrcode
qr_image = qrcode.make(uri)
return qr_image  # exibir para o usuário



O usuário abre seu aplicativo autenticador, toca em "escanear código QR" e o aplicativo lê o URI. O aplicativo extrai o segredo e começa a gerar códigos para aquela conta.

Etapa 3: Verificar um Código Inserido pelo Usuário

# Verificar o código no login
def verify_totp(user, user_entered_code):
   secret = decrypt(user.totp_secret)
   totp = pyotp.TOTP(secret)
   # valid_window=1 significa aceitar a janela de 30 segundos anterior e a próxima
   # em caso de desvio de relógio entre o servidor e o dispositivo do usuário
   return totp.verify(user_entered_code, valid_window=1)



O servidor calcula o código esperado a partir do segredo armazenado e o compara com o código inserido pelo usuário. A verificação é bem-sucedida se eles corresponderem dentro da janela de validade.

UX de Registro Que Realmente Funciona

Cinco padrões de UX separam um bom registro TOTP de um frustrante:

Mostrar o código QR E o segredo como texto

‍Usuários em dispositivos móveis não conseguem escanear facilmente o código QR na mesma tela. Exiba ambos: o código QR para configuração de desktop para celular, e o segredo como texto para usuários que o inserem manualmente em seu aplicativo autenticador.

Verificar o registro imediatamente

‍Depois que o usuário escanear o código QR, peça para ele inserir o código atual do seu aplicativo autenticador. Verifique-o antes de salvar o segredo como registrado. Isso detecta erros de configuração no registro, em vez de no primeiro login.

Gerar códigos de recuperação no registro

‍Gere 8-10 códigos de recuperação de uso único que o usuário salva antes de concluir o registro. Sem eles, usuários que perdem seu dispositivo não conseguem recuperar sua conta. Armazene os códigos de recuperação com hash em seu banco de dados; marque cada um como usado após o consumo.

Permitir múltiplos aplicativos autenticadores

‍Alguns usuários usam o Google Authenticator no telefone e o Authy no desktop. O padrão TOTP suporta o mesmo segredo registrado em múltiplos aplicativos simultaneamente. Seu fluxo de registro deve deixar isso claro.

Mostrar qual aplicativo instalar

‍A maioria dos usuários nunca viu TOTP antes. Mostre os quatro aplicativos mais populares (Google Authenticator, Microsoft Authenticator, Authy, 1Password) com links para download durante o registro.

Referência de Biblioteca: TOTP nas Principais Linguagens

LinguagemBibliotecaInstalaçãoNode.js / TypeScriptotplibnpm install otplibPythonpyotppip install pyotpJavajava-otpMaven: com.eatthepath:java-otpPHPotphpcomposer require spomky-labs/otphpGootpgo get github.com/pquerna/otpRubyrotpgem install rotpRusttotp-rsCargo: totp-rs.NETOtp.NETNuGet: Otp.NET

Todas implementam o RFC 6238 da mesma forma. Escolha a biblioteca para sua linguagem; a superfície da API é essencialmente idêntica (gerar segredo, construir URI, verificar código).

Erros Comuns de Implementação

Armazenar o segredo em texto simples

‍O segredo é a chave compartilhada; qualquer um com ele pode calcular os códigos do usuário. Criptografe em repouso com chaves gerenciadas pelo provedor ou pelo cliente.

Pular a etapa dos códigos de recuperação

‍Usuários que perdem seu dispositivo sem códigos de recuperação precisam passar por verificação manual de identidade com sua equipe de suporte. Códigos de recuperação gerados no registro custam zero e economizam horas de tempo de suporte por usuário bloqueado.

Sem tolerância a desvio de relógio

‍Se o relógio do seu servidor e o relógio do dispositivo do usuário tiverem um desvio de mais de 30 segundos, a verificação falhará. Use valid_window=1 (aceita janelas anterior e posterior) para tolerar pequenos desvios. Para maior tolerância, use valid_window=2.

Permitir que o mesmo código verifique duas vezes

‍Depois que um código for usado, marque o ID de verificação como consumido. Caso contrário, um invasor que espie o código poderá usá-lo dentro da janela de 30 segundos.

Não limitar a taxa de tentativas de verificação

‍Um ataque de força bruta a um código de 6 dígitos é viável sem limites de taxa. Limite a 5 tentativas por sessão, com espera exponencial depois.

Quando Avançar de TOTP para Passkey

O TOTP é substancialmente mais forte que o SMS OTP, mas mais fraco que as passkeys. A trajetória de maturidade típica:

1. SMS OTP no cadastro para cobertura universal (todos têm SMS).
2. Incentivar o registro de TOTP nos primeiros 30-90 dias para usuários preocupados com segurança.
3. Assim que o TOTP for amplamente adotado na sua base de usuários, incentive o registro de passkey como a próxima atualização.
4. Para ações administrativas de alto risco, exija chaves de hardware FIDO2, independentemente de outros fatores.

A FIDO Alliance publica o guia plurianual de migração para passkeys. Nosso guia de passkey vs OTP aborda as compensações.

Perguntas Frequentes

Por que usar TOTP se as passkeys são melhores?‍

O TOTP tem uma adoção mais ampla por parte dos usuários hoje do que as passkeys (usuários com Google Authenticator ou Authy instalados são comuns; usuários com passkeys registradas em seu serviço são mais raros em 2026). O TOTP também é o passo intermediário natural entre SMS OTP e passkeys para usuários que ainda não confiam nas passkeys ou cujos dispositivos não as suportam. Padrão: suporte os três.

O TOTP exige uma API de OTP?‍

Não para a verificação em si — os códigos são calculados no lado do cliente e verificados no lado do servidor usando uma biblioteca padrão. Mas você geralmente usa uma API de OTP juntamente com o TOTP para: (a) o fator inicial de SMS OTP no cadastro (verificar se o usuário é o proprietário do telefone antes de permitir o registro de TOTP), (b) recuperação de conta via SMS quando o usuário perde seu dispositivo TOTP, (c) fator de contingência em dispositivos onde o TOTP não está disponível.

Qual deve ser o comprimento do código TOTP?‍

O RFC 6238 suporta 6, 7 ou 8 dígitos. Seis dígitos é o padrão universal — todo aplicativo autenticador mostra códigos de 6 dígitos, e todo usuário os espera. Oito dígitos adicionam segurança marginal a um custo significativo para a experiência do usuário. Mantenha 6.

Adicione TOTP como a Camada de Alta Confiança em Sua Pilha Tecnológica

O TOTP é gratuito por verificação, resistente a phishing e o segundo fator ideal para usuários recorrentes preocupados com a segurança. Adicione-o juntamente com sua integração SMS OTP existente como uma opção de "melhoria" para usuários que desejam maior segurança. VerifyNow para os EUA gerencia a camada de SMS com rotas 10DLC e IDs de remetente pré-aprovados (comece a enviar em menos de 5 minutos); combine com a biblioteca TOTP de sua escolha para a camada de alta confiança. Créditos de teste gratuitos, sem necessidade de cartão de crédito.