Autenticação
A API da Dyvit aceita dois métodos de autenticação: JWT Token (via login com email e senha) e API Key (para integrações server-to-server). Ambos são enviados no header Authorization.
ℹ️ Email corporativo obrigatório. A Dyvit bloqueia cadastro e login com provedores pessoais como Gmail, Hotmail, Yahoo e similares. Use o email do domínio da sua empresa.
Ideal para aplicações frontend e fluxos que envolvem sessão de usuário. Obtenha um token via login com email e senha.
Login
POST/api/auth/login
Request body
| Campo | Tipo | Obrig. | Descrição |
|---|
| email | string | Sim | Email corporativo cadastrado na Dyvit |
| password | string | Sim | Senha da conta (mín. 8 caracteres, 1 maiúscula, 1 número) |
curl -X POST https://dyvit-api-production.up.railway.app/api/auth/login \
-H "Content-Type: application/json" \
-d '{
"email": "financeiro@acmefintech.com.br",
"password": "Dyvit2026!"
}'
200OK
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refreshToken": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f9a",
"client": {
"id": "cm1a2b3c4d5e6f7g8h9i0j",
"name": "Acme Fintech Ltda",
"email": "financeiro@acmefintech.com.br",
"plan": "GROWTH",
"status": "ACTIVE",
"trialEndsAt": "2026-04-02T00:00:00.000Z"
}
}
Usando o token
Inclua o JWT no header Authorization de todas as requisições autenticadas:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Expiração e refresh
O access token expira em 15 minutos. Use o refreshToken para obter um novo par sem precisar fazer login novamente.
POST/api/auth/refresh
Request body
| Campo | Tipo | Obrig. | Descrição |
|---|
| refreshToken | string | Sim | Refresh token retornado no login |
curl -X POST https://dyvit-api-production.up.railway.app/api/auth/refresh \
-H "Content-Type: application/json" \
-d '{
"refreshToken": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f9a"
}'
const res = await fetch(
"https://dyvit-api-production.up.railway.app/api/auth/refresh",
{
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
refreshToken: "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f9a",
}),
}
);
const { token, refreshToken: newRefresh } = await res.json();
// Descarte o refresh token antigo e use o novo
200OK
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refreshToken": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
⚠️ Rotação obrigatória. Cada refresh token só pode ser usado uma vez. Após o uso, ele é revogado e um novo é retornado. Se um refresh token já utilizado for reutilizado, todos os tokens do cliente são revogados por segurança, forçando um novo login.
O refresh token expira em 30 dias. Após esse prazo, o usuário precisa fazer login novamente.
Proteção contra brute force
O endpoint de login aplica rate limiting e lockout automático:
| Proteção | Regra |
|---|
| Rate limit | 5 requisições por minuto por IP |
| Lockout | Conta bloqueada por 15 minutos após 5 tentativas falhas consecutivas |
| Resposta de lockout | HTTP 423 com tempo restante de bloqueio |
Google OAuth
A Dyvit também aceita login via Google. Envie o Google ID Token no header Authorization: Bearer <google-id-token>. A API detecta automaticamente se o token é um JWT da Dyvit ou um ID Token do Google e valida de acordo.
ℹ️ Contas criadas exclusivamente via Google OAuth não possuem senha. Tentativas de login com email e senha retornam HTTP 422.
Ideal para integrações server-to-server, automações e importações via ERP. A API Key não expira e é mais simples de usar em scripts.
Gerar API Key
POST/api/onboarding/:clientId/api-key
Essa rota exige autenticação via JWT (Bearer token). Envie o clientId retornado no login.
CLIENT_ID="cm1a2b3c4d5e6f7g8h9i0j"
curl -X POST "https://dyvit-api-production.up.railway.app/api/onboarding/$CLIENT_ID/api-key" \
-H "Authorization: Bearer $TOKEN"
const clientId = "cm1a2b3c4d5e6f7g8h9i0j";
const res = await fetch(
`https://dyvit-api-production.up.railway.app/api/onboarding/${clientId}/api-key`,
{
method: "POST",
headers: { Authorization: `Bearer ${token}` },
}
);
const { apiKey } = await res.json();
console.log("API Key:", apiKey);
// Guarde esta chave em local seguro. Ela não será exibida novamente.
200OK
{
"apiKey": "dyvit_key_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6"
}
🚨 Exibida apenas uma vez. A API Key é mostrada somente na resposta desta requisição. Não é possível recuperá-la depois. Se você perdê-la, gere uma nova (a anterior será revogada automaticamente).
Usando a API Key
Envie a API Key no header Authorization com o prefixo Bearer:
Authorization: Bearer dyvit_key_a1b2c3d4e5f6g7h8i9j0...
A API detecta automaticamente se o token é um JWT ou uma API Key pelo prefixo dyvit_key_.
API Key vs JWT: quando usar cada um
| Critério | JWT Token | API Key |
|---|
| Caso de uso | Aplicações frontend, dashboards | Scripts, ERPs, automações |
| Expiração | 15 minutos (access) + 30 dias (refresh) | Nunca expira |
| Rotação | Automática via refresh token | Manual (gere uma nova) |
| Revogação | Logout ou expiração | Gerar nova chave (revoga a anterior) |
| Segurança | Mais seguro (curta duração) | Risco maior se exposta |
Erros comuns de autenticação
#| Status | Significado | O que fazer |
|---|
| 401 | Token ausente, inválido ou expirado | Faça login novamente ou use o refresh token |
| 403 | Conta inativa (PAUSED ou CANCELLED) | Entre em contato com o suporte |
| 422 | Conta usa apenas Google OAuth | Faça login via Google, não por email e senha |
| 423 | Conta bloqueada por tentativas falhas | Aguarde 15 minutos ou use "Esqueci minha senha" |