VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa

Autenticação avançada

Formas de entrar e recuperar acesso além de e-mail e senha: código, passkey, CNPJ, convite de contador.

O login com e-mail e senha, o cadastro e a renovação de sessão estão em Autenticação. Esta seção reúne o que vem além disso: entrar com um código de uso único, entrar com biometria (passkey), recuperar a senha de uma conta B2B pelo CNPJ, convidar um contador e deixar um cliente importado assumir o próprio cadastro.

Todas as rotas desta seção ficam sob /api/v1/auth/, funcionam no host da loja (a loja é identificada pelo domínio, veja Multi-loja) e devolvem erros no formato {"error": "...", "detail": "..."} descrito em Erros.

Pontos principais
  • A maioria é pública (sem token) e, por isso, protegida: limite de requisições por IP, bloqueio por tentativas e, se a loja configurar, reCAPTCHA no cabeçalho X-Recaptcha-Token.
  • Os fluxos nunca revelam se uma conta existe. Escreva as telas com mensagens do tipo "se existir uma conta, enviamos um código".
  • Alguns recursos dependem de módulos ligados pela loja (OTP, CNPJ, WebAuthn de step-up). Módulo desligado devolve 403 module_disabled.
  • Todos terminam em um par de tokens (access_token + refresh_token) ou em um reset_token. Veja Tokens e escopos.

Como escolher

Quero...Use
Entrar sem senha, por e-mail, SMS ou WhatsAppLogin por código
Entrar com Face ID, digital ou chave físicaLogin com passkey
Cadastrar passkey ou pedir biometria antes de uma ação sensívelCadastrar passkey e step-up
Ver ou apagar passkeysListar e remover passkeys
Recuperar a senha de conta empresarial por CNPJRecuperação B2B
Criar o acesso de um contadorConvite de contador
Reaproveitar cadastro importado de outra plataformaAdoção por CNPJ

Conceitos principais

Código de uso único (OTP)

Um OTP (one-time password) é um número de 6 dígitos, entregue ao e-mail, telefone ou WhatsApp do cliente, que vale por pouco tempo e para uma finalidade. A loja define a espera entre reenvios e o número máximo de tentativas.

Passkey e WebAuthn

WebAuthn é o padrão dos navegadores para autenticar com chaves criptográficas protegidas por biometria. A chave privada nunca sai do aparelho; a plataforma guarda só a chave pública. Cada passkey é presa ao domínio da loja.

Cerimônia

Nos fluxos de passkey, cada tentativa é uma cerimônia com um ceremony_id, criada no begin e consumida no finish. Vale 5 minutos e uma única vez.

Anti-enumeração

Rotas públicas que aceitam um identificador (e-mail, CNPJ, telefone) respondem igual para contas que existem e que não existem. Se o seu sistema precisa saber se um cliente existe, use as rotas administrativas, com token.

Endpoints

MétodoRotaPara quêAutenticação
POST/api/v1/auth/otp-login/requestPede um código de login por e-mail, SMS ou WhatsApp.Pública
POST/api/v1/auth/otp-login/verifyTroca o código por tokens.Pública
POST/api/v1/auth/webauthn/login/beginInicia o login com passkey.Pública
POST/api/v1/auth/webauthn/login/finishConclui o login com passkey.Pública
POST/api/v1/auth/webauthn/register/beginInicia o cadastro da passkey.Token
POST/api/v1/auth/webauthn/register/finishConclui o cadastro da passkey.Token
POST/api/v1/auth/webauthn/stepup/beginInicia a confirmação por biometria.Token
POST/api/v1/auth/webauthn/stepup/finishEmite o token de step-up.Token
GET/api/v1/auth/webauthn/credentialsLista as passkeys do usuário.Token
DELETE/api/v1/auth/webauthn/credentials/{id}Remove uma passkey.Token
GET/api/v1/auth/b2b-recovery/statusCanais de recuperação ligados na loja.Pública
POST/api/v1/auth/b2b-recovery/lookupIdentifica a conta por CNPJ, e-mail ou telefone.Pública
POST/api/v1/auth/b2b-recovery/sendEnvia o código de recuperação.Pública
POST/api/v1/auth/b2b-recovery/validateValida o código e devolve o reset_token.Pública
POST/api/v1/auth/accountant-invites/{token}/acceptAceita o convite e cria o contador.Pública (token do convite)
POST/api/v1/auth/cnpj-adoption/otp/requestEnvia o código de adoção ao e-mail antigo.Pública

Erros comuns

  • Tratar 200 de otp-login/request ou de b2b-recovery/send como "o código foi entregue". Significa só que o pedido foi aceito.
  • Chamar essas rotas de um servidor próprio para muitos clientes: o limite é por IP, então todos os seus clientes dividem a mesma cota. Faça as chamadas do navegador ou do app do cliente.
  • Reutilizar um ceremony_id ou deixá-lo passar de 5 minutos.
  • Guardar o reset_token do b2b-recovery/validate em log ou na URL.
  • Usar uma passkey em outra loja ou domínio: ela só vale onde foi cadastrada.
  • Esquecer o cabeçalho X-Recaptcha-Token em lojas que usam reCAPTCHA (erro captcha_required).

Próximos passos

Login por código
Entrada sem senha por e-mail, SMS ou WhatsApp.
Login com passkey
WebAuthn em duas chamadas.
Tokens e escopos
O que o seu token contém e quando expira.
Limites de requisições
Cotas por IP nas rotas públicas.
Anterior
Verificações de formato
Próxima
Login por código (OTP)
Nesta página
  • Como escolher
  • Conceitos principais
  • Código de uso único (OTP)
  • Passkey e WebAuthn
  • Cerimônia
  • Anti-enumeração
  • Endpoints
  • Erros comuns
  • Próximos passos