Autenticação

Como uma pessoa ou um sistema obtém, renova e encerra uma sessão na API da Venddor.

Toda chamada autenticada da API carrega um token de acesso (um JWT) no cabeçalho Authorization: Bearer. As rotas desta seção são as que emitem, renovam e encerram esse token, e as que criam e recuperam a conta de quem o usa. Elas ficam sob /api/v1/auth e servem os três tipos de usuário da plataforma: administrador, seller (lojista) e cliente.

Como funciona

O ciclo de uma sessão tem quatro momentos.

Entrar
Envie e-mail (ou CPF, ou CNPJ) e senha para POST /auth/login. A resposta traz access_token, refresh_token e expires_at. Se o usuário ativou o segundo fator (2FA), a resposta traz requires_2fa e um temp_token, e você conclui em POST /auth/verify-2fa.
Chamar a API
Mande Authorization: Bearer <access_token> em cada requisição, sempre pelo endereço da loja (veja Multi-loja e hosts).
Renovar
Perto do expires_at, troque o refresh_token por um par novo em POST /auth/refresh. O refresh token antigo deixa de valer.
Sair
POST /auth/logout encerra só o aparelho atual; POST /auth/logout-all encerra todos.

Conceitos principais

Quem usa cada rota

Ator	Como entra	Observação
Cliente (comprador da loja)	`/auth/register` e `/auth/login`	Cadastro livre; a loja pode exigir aprovação ou e-mail verificado.
Seller (lojista)	`/auth/vendor-register` e o mesmo login	A candidatura costuma ficar pendente até um administrador aprovar.
Administrador	O mesmo login, com usuário do tipo administrador	Contas de administrador da plataforma (painel IO) não entram por aqui e recebem `wrong_panel`.

Para entender qual família de rotas cada ator chama depois do login, leia Os três atores.

O campo identifier aceita e-mail, CPF (11 dígitos) ou CNPJ (14 dígitos); o servidor detecta o tipo. O campo antigo email continua aceito. Se vários usuários compartilham o mesmo CPF, CNPJ ou telefone, a API devolve 409 pedindo o login por e-mail.

Senha

Uma senha nova precisa ter pelo menos 10 caracteres, com letra maiúscula, minúscula, dígito e símbolo. A resposta de erro só devolve o código password_too_weak; não explica qual regra falhou.

Tempo de vida

Item	Duração padrão
Token de acesso	15 minutos (configurável por ambiente; sempre confira `expires_at`)
Refresh token	7 dias
`temp_token` do 2FA	5 minutos
Link de redefinição de senha	24 horas
Link de verificação de e-mail	72 horas

Captcha

Se a loja ativou o módulo de reCAPTCHA, as rotas de login, cadastro, recuperação de senha e reenvio de verificação exigem o cabeçalho X-Recaptcha-Token. Sem ele a resposta é 403 captcha_required. Para integração de servidor, veja os tipos de token em Tokens e escopos.

Endpoints

Método	Caminho	Para que serve	Auth	Página
POST	`/api/v1/auth/login`	Entrar com e-mail, CPF ou CNPJ e senha	nenhuma	Login
POST	`/api/v1/auth/verify-2fa`	Concluir o login com o código do segundo fator	nenhuma (usa `temp_token`)	Login
POST	`/api/v1/auth/register`	Cadastrar um cliente	nenhuma	Cadastro
POST	`/api/v1/auth/vendor-register`	Candidatura de seller	nenhuma	Cadastro
POST	`/api/v1/auth/refresh`	Trocar o refresh token por um par novo	nenhuma (usa o refresh token)	Sessão
POST	`/api/v1/auth/logout`	Encerrar a sessão deste aparelho	token ou refresh token	Sessão
POST	`/api/v1/auth/logout-all`	Encerrar todas as sessões	token de acesso	Sessão
POST	`/api/v1/auth/forgot-password`	Pedir o e-mail de redefinição	nenhuma	Senha
POST	`/api/v1/auth/reset-password`	Definir a senha nova com o token do e-mail	nenhuma (usa o token)	Senha
POST	`/api/v1/auth/verify-email`	Confirmar o e-mail com o token recebido	nenhuma (usa o token)	Verificação de e-mail
POST	`/api/v1/auth/verify-email/request`	Reenviar a verificação ao usuário logado	qualquer usuário logado	Verificação de e-mail
POST	`/api/v1/auth/verify-email/resend`	Reenviar a verificação sem login	nenhuma	Verificação de e-mail
GET	`/api/v1/auth/check-email`	Validar o formato de um e-mail	nenhuma	Verificações de formato
GET	`/api/v1/auth/check-cpf`	Validar um CPF	nenhuma	Verificações de formato
GET	`/api/v1/auth/check-cnpj`	Validar um CNPJ	nenhuma	Verificações de formato

Login sem senha por código (OTP), chaves de acesso (passkeys), recuperação B2B e convite de contador estão em Autenticação avançada.

Erros comuns

Logar a cada chamada. O login tem limite de 5 por minuto por IP; o excesso volta 429. Guarde o token e renove com o refresh token.
Reusar um refresh token. Cada renovação gera um refresh token novo e invalida o anterior. Guarde sempre o último par recebido.
Mandar o token de uma loja para outra. O token carrega o tenant_id da loja que o emitiu; em outra loja ele é recusado.
Tratar 403 de login como senha errada. Contas pendentes de aprovação, desativadas ou sem e-mail verificado recebem 403 com um código próprio (veja a página de login). A senha estava certa.
Usar check-email para saber se a conta existe. Ele só valida o formato e sempre diz available: true. Quem decide é o cadastro.
Esperar mensagem em português ou inglês fixa. O campo error é um código ou frase curta em inglês; faça a lógica pelo código, não pelo texto. Veja Erros.

Próximos passos

Entrar, 2FA e as respostas de bloqueio.

Tokens e escopos

O que há dentro do token e como ele é revogado.

Limites de requisição

Todos os limites por rota.

API atual/Referência completa

Autenticação

Como uma pessoa ou um sistema obtém, renova e encerra uma sessão na API da Venddor.

Como funciona

O ciclo de uma sessão tem quatro momentos.

Entrar
Envie e-mail (ou CPF, ou CNPJ) e senha para POST /auth/login. A resposta traz access_token, refresh_token e expires_at. Se o usuário ativou o segundo fator (2FA), a resposta traz requires_2fa e um temp_token, e você conclui em POST /auth/verify-2fa.
Chamar a API
Mande Authorization: Bearer <access_token> em cada requisição, sempre pelo endereço da loja (veja Multi-loja e hosts).
Renovar
Perto do expires_at, troque o refresh_token por um par novo em POST /auth/refresh. O refresh token antigo deixa de valer.
Sair
POST /auth/logout encerra só o aparelho atual; POST /auth/logout-all encerra todos.

Conceitos principais

Quem usa cada rota

Ator	Como entra	Observação
Cliente (comprador da loja)	`/auth/register` e `/auth/login`	Cadastro livre; a loja pode exigir aprovação ou e-mail verificado.
Seller (lojista)	`/auth/vendor-register` e o mesmo login	A candidatura costuma ficar pendente até um administrador aprovar.
Administrador	O mesmo login, com usuário do tipo administrador	Contas de administrador da plataforma (painel IO) não entram por aqui e recebem `wrong_panel`.

Para entender qual família de rotas cada ator chama depois do login, leia Os três atores.

Senha

Tempo de vida

Item	Duração padrão
Token de acesso	15 minutos (configurável por ambiente; sempre confira `expires_at`)
Refresh token	7 dias
`temp_token` do 2FA	5 minutos
Link de redefinição de senha	24 horas
Link de verificação de e-mail	72 horas

Captcha

Endpoints

Método	Caminho	Para que serve	Auth	Página
POST	`/api/v1/auth/login`	Entrar com e-mail, CPF ou CNPJ e senha	nenhuma	Login
POST	`/api/v1/auth/verify-2fa`	Concluir o login com o código do segundo fator	nenhuma (usa `temp_token`)	Login
POST	`/api/v1/auth/register`	Cadastrar um cliente	nenhuma	Cadastro
POST	`/api/v1/auth/vendor-register`	Candidatura de seller	nenhuma	Cadastro
POST	`/api/v1/auth/refresh`	Trocar o refresh token por um par novo	nenhuma (usa o refresh token)	Sessão
POST	`/api/v1/auth/logout`	Encerrar a sessão deste aparelho	token ou refresh token	Sessão
POST	`/api/v1/auth/logout-all`	Encerrar todas as sessões	token de acesso	Sessão
POST	`/api/v1/auth/forgot-password`	Pedir o e-mail de redefinição	nenhuma	Senha
POST	`/api/v1/auth/reset-password`	Definir a senha nova com o token do e-mail	nenhuma (usa o token)	Senha
POST	`/api/v1/auth/verify-email`	Confirmar o e-mail com o token recebido	nenhuma (usa o token)	Verificação de e-mail
POST	`/api/v1/auth/verify-email/request`	Reenviar a verificação ao usuário logado	qualquer usuário logado	Verificação de e-mail
POST	`/api/v1/auth/verify-email/resend`	Reenviar a verificação sem login	nenhuma	Verificação de e-mail
GET	`/api/v1/auth/check-email`	Validar o formato de um e-mail	nenhuma	Verificações de formato
GET	`/api/v1/auth/check-cpf`	Validar um CPF	nenhuma	Verificações de formato
GET	`/api/v1/auth/check-cnpj`	Validar um CNPJ	nenhuma	Verificações de formato

Login sem senha por código (OTP), chaves de acesso (passkeys), recuperação B2B e convite de contador estão em Autenticação avançada.

Erros comuns

Logar a cada chamada. O login tem limite de 5 por minuto por IP; o excesso volta 429. Guarde o token e renove com o refresh token.
Reusar um refresh token. Cada renovação gera um refresh token novo e invalida o anterior. Guarde sempre o último par recebido.
Mandar o token de uma loja para outra. O token carrega o tenant_id da loja que o emitiu; em outra loja ele é recusado.
Tratar 403 de login como senha errada. Contas pendentes de aprovação, desativadas ou sem e-mail verificado recebem 403 com um código próprio (veja a página de login). A senha estava certa.
Usar check-email para saber se a conta existe. Ele só valida o formato e sempre diz available: true. Quem decide é o cadastro.
Esperar mensagem em português ou inglês fixa. O campo error é um código ou frase curta em inglês; faça a lógica pelo código, não pelo texto. Veja Erros.

Próximos passos

Entrar, 2FA e as respostas de bloqueio.

Tokens e escopos

O que há dentro do token e como ele é revogado.

Limites de requisição

Todos os limites por rota.