Autenticação

A engineAPI suporta dois métodos de autenticação. Como cada credencial chega até a chamada:

API Key

Para automações, SDKs e integrações server-to-server: o caso comum de software house. Gerada no cadastro ou no Dashboard, nunca expira (até ser revogada).

JWT (Bearer Token)

Para o dashboard e sessões de usuário. Obtenha via POST /v1/auth/login e use no header Authorization.

POST /v1/auth/resend-verification e GET /v1/auth/verification-status mexem só na conta do JWT, inclusive quando o login ainda não tem parceiro vinculado (por exemplo, operador da plataforma no painel admin).

Cadastro pelo site (POST /v1/auth/register) cria a conta na hora e responde 202: pedido de acesso já aprovado, partner no plano Dev (R$ 0), convite de dono por e-mail e assinatura ativa, tudo na mesma transação, e a senha é criada no aceite do convite. E-mail já em uso devolve a mesma resposta sem criar nada; o teto é de 3 contas por IP a cada 24 h e e-mail descartável recusa com 422. Os limites por IP se aplicam também a e-mails já usados. Ver Quickstart para o passo a passo. Quem libera um pedido pelo admin, inclusive SUPERADMIN, recebe só o prefixo e um aviso, sem a chave de API nem o link de aceite. O convite chega por e-mail ao dono, que gera a chave no próprio painel depois de aceitá-lo. POST /v1/auth/register-partner continua existindo para provisionamento manual por um parceiro com papel SUPERADMIN.

Método 1: JWT (Bearer Token)

Use quando seu backend/dashboard faz login com e-mail e senha.

Obtendo o token

cURL
Node.js
Python

curl -X POST https://api.engineapi.com.br/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@minhaempresa.com",
    "password": "suaSenha"
  }'

const response = await fetch('https://api.engineapi.com.br/v1/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'dev@minhaempresa.com',
    password: 'suaSenha',
  }),
});

const { data } = await response.json();
// data.access_token, data.user.{id,email,name,partnerId,role}

import httpx

resp = httpx.post('https://api.engineapi.com.br/v1/auth/login', json={
    'email': 'dev@minhaempresa.com',
    'password': 'suaSenha',
})

token = resp.json()['data']['access_token']

Resposta (201)

{
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "user": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "email": "dev@minhaempresa.com",
      "name": "Admin",
      "partnerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "role": "ADMIN"
    }
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2026-07-06T12:00:00.000Z"
  }
}

A resposta é 201 Created, não 200 OK (versões anteriores desta doc afirmavam 200). Trate qualquer resposta 2xx como sucesso, em vez de checar um código exato.

Toda resposta de sucesso vem envelopada em { data, meta }: meta.requestId/meta.timestamp são preenchidos automaticamente pelo interceptor global. Isso vale para todas as respostas desta documentação, não só o login.

Usando o token

curl -X GET https://api.engineapi.com.br/v1/companies \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Expiração e renovação

Campo	Valor
Duração do access token	12 horas
Formato	JWT assinado com HS256
Header	`Authorization: Bearer <token>`
Refresh token	30 dias, rotacionado a cada uso

O login devolve access_token e refresh_token. Quando o access token expira, troque-o por um par novo:

curl -X POST https://api.engineapi.com.br/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "SEU_REFRESH_TOKEN"}'

A rotação é obrigatória: o refresh token usado morre na mesma chamada. Guarde sempre o refresh_token novo que veio na resposta: reapresentar o antigo devolve 401. Para encerrar a sessão:

# encerra só esta sessão
curl -X POST https://api.engineapi.com.br/v1/auth/logout \
  -H "Authorization: Bearer SEU_TOKEN"

# encerra todas as sessões da conta
curl -X POST "https://api.engineapi.com.br/v1/auth/logout?all=true" \
  -H "Authorization: Bearer SEU_TOKEN"

O logout invalida o access token na hora: ele não continua valendo até expirar. Trocar a senha também derruba todas as sessões abertas.

Nunca exponha seu token no frontend, em logs ou em repositórios públicos. Use variáveis de ambiente.

Verificação em duas etapas (2FA)

Contas com acesso privilegiado (superadmin da plataforma e dono de parceiro, PartnerMember.role = OWNER) são obrigadas a usar um aplicativo autenticador (TOTP, RFC 6238). Para as demais é opcional, ligável em Configurações → Segurança. Quando a conta tem 2FA ativo, o POST /v1/auth/login responde sem access_token:

{
  "mfa_required": true,
  "mfa_enrollment_required": false,
  "mfa_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_in": 300
}

Conclua com o código de 6 dígitos do autenticador:

curl -X POST https://api.engineapi.com.br/v1/auth/2fa/verify \
  -H "Content-Type: application/json" \
  -d '{"mfaToken": "SEU_MFA_TOKEN", "totpCode": "123456"}'

Clientes que preferem uma chamada só podem mandar o código junto no login (totpCode no corpo do POST /v1/auth/login).

Campo da resposta	O que significa
`mfa_required: true`	A conta tem 2FA ativo, falta o código
`mfa_enrollment_required: true`	O papel exige 2FA e a conta ainda não configurou. Use o `mfa_token` em `POST /v1/auth/2fa/setup` e `POST /v1/auth/2fa/enable`
`mfa_token`	Credencial de propósito único, válida por 5 minutos. Não vale como `Bearer` nas demais rotas

Os dois formatos de resposta do login (sessão completa ou 2FA pendente) são as alternativas do 200 declaradas no contrato OpenAPI. Perdeu o celular? Envie um dos códigos de recuperação em recoveryCode no lugar de totpCode. Cada código funciona uma única vez, e o titular (mais o dono da plataforma) recebe um e-mail avisando que um deles foi usado. Tentativas falhas bloqueiam progressivamente, por e-mail e por IP: 5 falhas → 1 minuto, 10 → 15 minutos, 15 → 1 hora, 20 → 4 horas. Um balde sem falha nova por 1 hora zera sozinho, e um login bem-sucedido limpa o balde do e-mail. Enquanto o bloqueio vale, a senha certa também é recusada. A resposta é sempre a mesma (401 Credenciais inválidas) para senha errada, e-mail inexistente, código 2FA errado e conta bloqueada: a API não confirma quais e-mails existem.

Método 2: API Key

Use em automações de longa duração, SDKs ou integrações server-to-server sem sessão de login.

Gerando uma API Key

Acesse o Dashboard → app.engineapi.com.br
Vá em Configurações → API Keys
Gere a key de teste (ek_test_), disponível sem assinatura paga, ou a key de produção (ek_live_), que exige uma subscription ACTIVE (403 sem plano pago)
Copie e guarde. Ela é exibida uma única vez

A conta criada pelo site ou aprovada pelo admin nasce sem chave. A de teste e a de produção são geradas no painel; a de produção exige plano pago ativo. Via API (sessão JWT do dashboard):

# Key de teste: qualquer partner, sem exigir assinatura
curl -X POST https://api.engineapi.com.br/v1/auth/api-keys/test/regenerate \
  -H "Authorization: Bearer SEU_TOKEN"

# Key de produção: exige subscription ACTIVE
curl -X POST https://api.engineapi.com.br/v1/auth/api-keys/regenerate \
  -H "Authorization: Bearer SEU_TOKEN"

Usando a API Key

/v1/companies aceita x-api-key ou JWT (ApiKeyGuard, mesmo escopo de partner nos dois casos); este exemplo funciona de ponta a ponta.

cURL
Node.js / SDK
Python

curl -X GET https://api.engineapi.com.br/v1/companies \
  -H "x-api-key: ek_live_xxxxxxxxxxxxxxxx"

import { EngineApiClient } from '@engineapi/sdk';

const client = new EngineApiClient({
  baseUrl: 'https://api.engineapi.com.br', // sem /v1, o SDK adiciona
  apiKey: process.env.ENGINE_API_KEY!,     // ek_live_... ou ek_test_...
});

const companies = await client.companies.listar();

import httpx

resp = httpx.get('https://api.engineapi.com.br/v1/companies',
    headers={'x-api-key': 'ek_live_xxxxxxxxxxxxxxxx'},
)

Propriedade	Detalhe
Header	`x-api-key: ek_live_...` (produção) ou `x-api-key: ek_test_...` (teste)
Prefixo	`ek_live_` (produção) / `ek_test_` (teste: homologação/sandbox, não faturado)
Expiração	Nunca. Revogue/regenere manualmente pelo Dashboard ou pela API

A ek_test_ só opera emissores em homologação (ambienteFiscal=2) ou marcados como sandbox. Usá-la contra um emissor de produção retorna 403. Emissões com ek_test_ não são faturadas.

Multi-tenancy

Um único token (JWT) ou API Key gerencia múltiplos CNPJs emissores (Issuer) sob o mesmo Partner:

Partner (seu token / API key)
├── Empresa A (issuerId: "uuid-a")
├── Empresa B (issuerId: "uuid-b")
└── Empresa C (issuerId: "uuid-c")

Seleção explícita de emissor: NF-e, NFC-e e NFS-e aceitam issuerId (UUID) no corpo da emissão para escolher qual CNPJ emite a nota.

NF-e / NFC-e: issuerId é opcional:
- se você tem um único emissor, pode omitir: a API usa o seu emissor (retrocompatível);
- se você tem dois ou mais emissores, informe issuerId; sem ele a API responde 400 (“informe issuerId: sua conta tem N emissores”) em vez de emitir pelo CNPJ errado;
- um issuerId que não pertence ao partner autenticado responde 404 (isolamento entre tenants).
NFS-e: issuerId é obrigatório no corpo da requisição.

// POST /v1/nfe  (ou /v1/nfce, /v1/nfse)
{
  "issuerId": "uuid-a",   // opcional em NFe/NFCe; obrigatório em NFSe
  "destinatario": { "...": "..." },
  "items": [ "..." ]
}

O issuerId (UUID) é retornado ao criar uma empresa via POST /v1/companies.

Reenviar convite de dono

Se o convite não chegar ou tiver expirado, use Não recebeu o convite? no sucesso do cadastro ou na tela do convite. Informe o e-mail do cadastro para receber outro link, válido por sete dias. O novo link substitui os anteriores. A API pública POST /auth/invite/resend recebe { "email": "dono@example.com" } e responde 202 com mensagem neutra, inclusive para e-mail inexistente ou conta já ativa. Só reenvia convites de dono ainda não aceitos. O quarto pedido em uma hora por e-mail ou o sexto em um minuto por IP responde 429. O e-mail é normalizado antes da contagem; o token nunca aparece na resposta ou nos logs.

Comece aqui

Emissão

Tributação

Erros e operação

IA e automação

Conceitos

Migração

Perguntas frequentes

API Key

JWT (Bearer Token)

Método 1: JWT (Bearer Token)

Obtendo o token

Usando o token

Expiração e renovação

Verificação em duas etapas (2FA)

Método 2: API Key

Gerando uma API Key

Usando a API Key

Multi-tenancy

Reenviar convite de dono

API Key

JWT (Bearer Token)

Método 1: JWT (Bearer Token)

Obtendo o token

Usando o token

Expiração e renovação

Verificação em duas etapas (2FA)

Bloqueio por tentativas de login

Método 2: API Key

Gerando uma API Key

Usando a API Key

Multi-tenancy

Reenviar convite de dono