Skip to Content
GuiasAutenticação + API keys

Autenticação

A API usa Bearer token simples no header Authorization. Não tem OAuth flow no servidor — toda integração é máquina-a-máquina com uma API key.

curl -H "Authorization: Bearer fk_live_..." https://api.zfiscoo.zek.app.br/v1/nfce

Tipos de key

PrefixoQuando usaHits SEFAZ real?
fk_live_xxxxxxxxxxxxxxxxProdução✅ Sim — emite notas válidas
fk_test_xxxxxxxxxxxxxxxxSandbox conta-própria❌ Mock SEFAZ embarcado
fk_sandbox_publicSandbox público sem cadastro❌ Mock + DB reseta 04:00 UTC

Cada key pertence a uma Application (que pertence a uma Account). Uma Account pode ter N Applications — útil pra ambientes (dev/staging/prod) ou pra isolar consumidores diferentes.

Criando keys

portal-zfiscoo.zek.app.br/applications  → Nova Application. Cada Application tem:

  • Nome (display)
  • Type (live | test)
  • Scopes (opcional — array; vazio = full access)
  • Rate-limit (req/min, default 600)

A chave aparece uma única vez — armazene em variável de ambiente. Se perder, gere uma nova (a antiga é revogada após confirmação).

Scopes

Quando você quer dar a um consumidor (ex: integrador terceiro) acesso parcial:

ScopePermite
nfce:readGET nfce
nfce:writePOST/PUT/DELETE nfce, cancel, inutilization
nfe:read / nfe:writeAnálogo pra NF-e mod 55
nfse:read / nfse:writeNFS-e
issuers:read / issuers:writeCRUD Issuer, cert, CSC
webhooks:manageCRUD webhooks
account:readBilling + audit log read

Sem scopes (array vazio) = full access (recomendado pra apps internas).

Rate-limit per key

Cada Application tem rate-limit independente, default 600 req/min. Headers em toda resposta:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 587
X-RateLimit-Reset: 1715442300
X-RateLimit-Window: 60

X-RateLimit-Reset é epoch (seconds) em que a janela atual reseta. Se ultrapassar, recebe 429 Too Many Requests.

Audit log

Toda chamada autenticada (login, criação de issuer, cancelamento, etc) vai pro audit log com:

  • actor_type = 'api_key' | 'user'
  • actor_id (Application.id ou User.id)
  • action (nfce.issued, cert.uploaded, webhook.deleted, etc)
  • ip, user_agent
  • metadata (JSON com dados relevantes do request)

Acessível em GET /v1/audit-log (scope account:read ou role admin+).

Dashboard: 2FA + SSO

Login no dashboard tem proteções extras (a API key continua sendo o método pra integração programática):

  • 2FA TOTP (otplib) — setup com QR code, 10 recovery codes one-shot SHA-256
  • SSO Google/Microsoft OAuth (roadmap Q3 2026)
  • Team RBAC — 5 roles: owner / admin / developer / billing / viewer
🔒

Nunca commite fk_live_... no repositório. Use secrets manager (GitHub Secrets, Vault, AWS Secrets Manager). O gateway detecta keys vazadas em payloads de webhook e bloqueia/notifica.

Idempotency-KeyReforma Tributária 2026