O que é a Chave Restrita

A Chave Restrita (X-Restricted-Key, prefixo nfe_restricted_) é uma credencial adicional, separada da Chave de Acesso, que existe só para autorizar a leitura programática dos tokens (nfe_test_/nfe_live_) de qualquer cliente da conta — inclusive o de produção — sem exigir a senha da conta a cada consulta, como o painel exige. É usada no endpoint Obter os tokens de um cliente, sempre em conjunto com a Chave de Acesso.

Gere, veja ou regenere a sua em Painel → Chaves de API (card à direita).

Por que ela existe

No painel, ver um token de produção sempre pede a senha da conta — proteção contra vazamento acidental ou roubo de sessão. Uma integração automatizada (por exemplo, um fluxo que cria o cliente via API e, na sequência, precisa do token dele para emitir notas) não tem como digitar uma senha interativamente.

A Chave Restrita substitui essa senha: quem apresenta a Chave de Acesso e a Chave Restrita já provou posse suficiente para dispensar a confirmação manual.

Por que é perigosa

Possuir as duas chaves de uma conta é equivalente a ter acesso de leitura a todas as credenciais de produção de todos os clientes daquela conta, via API, sem fricção nenhuma.

Trate como a senha mestra da conta

A Chave Restrita dá acesso total de leitura às credenciais de produção de todos os seus clientes cadastrados. Nunca a compartilhe, nunca a coloque em repositórios de código, e revogue-a imediatamente se desconfiar que foi exposta.

É por isso que:

• ela vem oculta por padrão no painel (mascarada, só prefixo + últimos 4 caracteres);
• só é revelada digitando a senha da conta (mesmo fluxo da Chave de Acesso);
• pode ser regenerada (invalida a anterior na hora) ou revogada a qualquer momento;
• a recomendação de uso é gerar uma chave por integração/automação (nunca reaproveitar), nunca commitar em código, nunca logar, e revogar imediatamente ao suspeitar de vazamento.

Boas práticas de uso

Escopo mínimo

Só peça a Chave Restrita para o fluxo específico que precisa ler tokens de produção programaticamente (tipicamente, o passo seguinte a criar um cliente). Qualquer outra chamada à API — emissão, consulta, cancelamento, listagem de clientes — usa só a Chave de Acesso e/ou o token do próprio cliente, e não deve receber a Chave Restrita.

• Armazene-a em um cofre de segredos (secrets manager), nunca em variáveis de ambiente versionadas ou arquivos de configuração commitados.
• Prefira gerar uma Chave Restrita dedicada por serviço/automação, para que revogar uma não afete as demais.
• Monitore o uso do endpoint GET /v1/clients/{cnpj}/tokens — ele já é limitado a 20 requisições/minuto por IP, mas um volume incomum de chamadas é um sinal de alerta.