// comece aqui

Autenticação

JWT e API Keys: como autenticar suas requisições na engineAPI.

Autenticação

A engineAPI suporta dois métodos de autenticação:

Cadastro self-service (POST /v1/auth/register) cria sua conta completa em uma chamada: partner, usuário ADMIN, plano Dev (R$0, ativo na hora) e uma API Key de teste (ek_test_...), sem falar com ninguém. Ver Quickstart para o passo a passo. POST /v1/auth/register-partner continua existindo para provisionamento manual por um parceiro com papel SUPERADMIN, mas não é mais o único caminho.

Método 1: JWT (Bearer Token)

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

Obtendo o token

bash

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

json

{
  "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). AuthController.login é um @Post() sem @HttpCode explícito: o Nest usa 201 como default pra POST. Verificado por request real contra o staging.

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

bash

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

Expiração

Campo	Valor
Duração	24 horas
Formato	JWT assinado com HS256
Header	`Authorization: Bearer <token>`

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

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

Via API (sessão JWT do dashboard):

bash

# 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.

bash

curl -X GET https://api.engineapi.com.br/v1/companies \
  -H "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:

font-mono text-sm bg-slate-800 text-[var(--eng-glow)] rounded px-1.5 py-0.5

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: NFe, NFCe e NFSe aceitam issuerId (UUID) no corpo da emissão para escolher qual CNPJ emite a nota.

NFe / NFCe: 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).
NFSe: issuerId é obrigatório no corpo da requisição.

json

// 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.