Autenticação: API keys e escopos

Toda chamada à API é autenticada por uma chave de API da empresa. A chave define o ambiente (teste ou produção) e o que ela pode fazer (escopos).

Formato da chave#

emt_<ambiente>_<prefixo>_<segredo>

emt_test_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx   ← teste (sandbox)
emt_live_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx   ← produção

• O prefixo (8 caracteres) identifica a chave no painel e nos logs.
• O segredo (32 caracteres) só existe com você. A Emitra guarda apenas um hash dele e não consegue mostrar a chave de novo.

Enviando a chave#

Use o header Authorization com o esquema Bearer:

GET /api/v1/integracao/me HTTP/1.1
Host: emitra.com.br
Authorization: Bearer emt_test_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

O header X-Api-Key: <chave> também é aceito, para ferramentas que não permitem mexer no Authorization.

curl https://emitra.com.br/api/v1/integracao/me \
  -H "Authorization: Bearer $EMITRA_API_KEY"

import os, requests

r = requests.get(
    "https://emitra.com.br/api/v1/integracao/me",
    headers={"Authorization": f"Bearer {os.environ['EMITRA_API_KEY']}"},
    timeout=30,
)

const r = await fetch("https://emitra.com.br/api/v1/integracao/me", {
  headers: { Authorization: `Bearer ${process.env.EMITRA_API_KEY}` },
});

<?php
$ch = curl_init("https://emitra.com.br/api/v1/integracao/me");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("EMITRA_API_KEY")],
    CURLOPT_RETURNTRANSFER => true,
]);
$resposta = json_decode(curl_exec($ch), true);

Criando uma chave#

Só owner e admin da empresa criam chaves (permissão integracao:gerenciar).

1. Abra Notas › Automação › Integrações › Chaves de API.
2. Clique em Nova chave e informe:
   • Nome (ex.: "ERP Produção");
   • Ambiente: teste (emt_test_) ou produção (emt_live_);
   • Escopos (veja abaixo);
   • Expiração: obrigatória, de até 1 ano.
3. Copie a chave e marque "Guardei a chave em um local seguro". Ela não será mostrada de novo.

Escopos#

As rotas de utilidade (/me, /referencia/*) aceitam qualquer chave válida.

Os escopos são um subconjunto das permissões de quem cria a chave. Um admin não consegue criar uma chave com um escopo que ele próprio não tem.

Respostas de autenticação#

A mensagem de erro é genérica de propósito: ela não diz se a chave existe.

Proteja sua chave#

• O painel mostra o último uso (data e IP) de cada chave. Revise as chaves sem uso e revogue.
• Toda ação feita por uma chave entra na auditoria da empresa com o ator api_key e o nome da chave.

Revogando e rotacionando#

Revogar tem efeito imediato: as chamadas seguintes recebem 401. Para rotacionar sem parar a integração:

1. Crie a chave nova com os mesmos escopos.
2. Publique a chave nova no seu sistema.
3. Confira no painel que a chave antiga parou de ser usada.
4. Revogue a chave antiga.

Próximos passos#

• Ambientes e URLs base
• Rate limits por plano
• Segurança e LGPD