OTP (One-Time Password)

Overview

O OTP é um mecanismo genérico de verificação que gera um código numérico de 6 dígitos, mantém apenas sua versão protegida e entrega o código ao usuário. Cada OTP está vinculado a um contexto que determina qual operação será autorizada após a verificação, como recuperação de senha, troca de telefone ou troca de email.

How It Works

A verificação ocorre dentro do fluxo que consome o OTP (ex.: reset-password), usando o otpId devolvido na solicitação junto com o code.

Registro

Campo	Tipo	Descrição
`otpId`	UUID	Identificador único (devolvido ao cliente na solicitação)
`userId`	UUID	Referência ao User
`code`	String	Credencial protegida do código (nunca armazenado em texto puro)
`context`	OtpContext	Contexto que determina a finalidade do OTP
`recipient`	String	Destinatário da entrega
`expiresAt`	DateTime	Data/hora de expiração (2 minutos após a criação)
`usedAt`	DateTime?	Data/hora de uso (`null` se não utilizado)
`createdBy`	UUID?	Usuário que criou o registro, quando aplicável
`createdAt`	DateTime	Data/hora de criação
`updatedBy`	UUID?	Usuário que fez a última atualização, quando aplicável
`updatedAt`	DateTime	Data/hora de última atualização

Supported Contexts

Context	Descrição	Ação pós-verificação
`RESET_PASSWORD`	Recuperação de senha	Define a nova senha do usuário e marca o OTP como usado
`RESET_PHONE`	Troca ou validação de telefone	Autoriza a atualização do telefone e marca o OTP como usado
`RESET_EMAIL`	Troca ou validação de email	Autoriza a atualização do email e marca o OTP como usado

Novos contextos podem ser adicionados conforme necessário (ex.: two-factor auth). O mecanismo de geração, entrega e verificação permanece o mesmo — apenas a ação pós-verificação muda.

Business Rules

Regra	Descrição
Validade	O código expira 2 minutos após a criação.
Credencial protegida em repouso	Apenas a versão protegida do código é mantida; o valor em texto puro só existe na entrega.
Uso único	Após verificação bem-sucedida, `usedAt` é preenchido e o código não pode ser reutilizado.
Proteção contra enumeração	Se o usuário não existir (ou não tiver telefone), a solicitação devolve um `otpId` aleatório sem criar nenhum OTP, evitando revelar quais contas existem.

O código OTP não é um token de autenticação. É um código de verificação de curta duração que, após validado, dispara a ação correspondente ao seu contexto.

Visão geral

Authorization

Benefits

Billing

Communication

Credit Grant

Export

Fleet

Identity

Observability

Operations

Platform

Sales

Support

Tenant

Overview

How It Works

Registro

Supported Contexts

Business Rules

​Overview

​How It Works

​Registro

​Supported Contexts

​Business Rules

Overview

How It Works

Registro

Supported Contexts

Business Rules