---
title: "Autenticação"
description: "Como autenticar na API do Emissor de Nota: chave Bearer, tipos de chave (edn_live_ e edn_test_), escopos, restrições opcionais, erros 401/403 e rotação."
url: https://docs.emissordenota.com/autenticacao
language: pt-BR
---
# Autenticação

Toda chamada leva uma chave de API no cabeçalho Authorization. A chave identifica a organização e define quais empresas e recursos ela alcança.

## Enviando a chave

Use o esquema Bearer. Chamadas sem HTTPS são recusadas, e a chave nunca vai na URL.

**cURL**

```bash
curl https://api.emissordenota.com/v1/nfse \
  -H "Authorization: Bearer edn_live_SUA_CHAVE"
```

## Tipos de chave

O prefixo diz em qual ambiente a chave funciona. Uma chave de sandbox enviada para produção devolve 401, e vice-versa.

| Prefixo | Ambiente | Comportamento |
| --- | --- | --- |
| edn_live_ | Produção | Emite notas com valor fiscal e consulta dados reais da carteira |
| edn_test_ | Sandbox | Simula emissão e guias. Nada é transmitido |

## Permissões

Cada chave recebe permissões por recurso, escolhidas na hora de gerar. Dê só o que a integração usa.

| Escopo | Permite |
| --- | --- |
| nfse:ler | Consultar notas e baixar XML e PDF |
| nfse:escrever | Emitir, cancelar e substituir notas |
| empresas:ler | Listar as empresas da carteira e seus certificados |
| empresas:escrever | Cadastrar e editar empresas |
| cadastros:ler | Consultar clientes e serviços |
| cadastros:escrever | Criar e editar clientes e serviços |
| guias:ler | Consultar guias e baixar o PDF |
| ecac:avisos | Receber avisos de novas mensagens no e-CAC |
| webhooks:escrever | Cadastrar e remover endpoints de webhook |

## Restrições opcionais

- Empresas: limite a chave a algumas empresas da carteira em vez de todas.
- Endereços IP: aceite chamadas apenas dos IPs fixos do seu servidor.
- Validade: defina expiração em 30, 90 ou 365 dias. Chaves sem validade continuam ativas até serem revogadas.

## Quando a chave é recusada

| Status | Código | Motivo |
| --- | --- | --- |
| 401 | chave_invalida | Chave ausente, mal formatada, revogada ou do ambiente errado |
| 401 | chave_expirada | A validade definida na criação terminou |
| 403 | permissao_insuficiente | A chave não tem o escopo que o endpoint exige |
| 403 | empresa_nao_autorizada | A empresa não está entre as liberadas para a chave |
| 403 | ip_nao_autorizado | A chamada veio de um IP fora da lista |

**403 Forbidden**

```json
{
  "erro": {
    "codigo": "permissao_insuficiente",
    "mensagem": "Esta chave não tem o escopo nfse:escrever.",
    "requisicao_id": "req_7Hc2Lq9Vx1"
  }
}
```

## Rotação e revogação

Para trocar uma chave sem parar a integração, gere a nova, publique no seu sistema e só então revogue a antiga em Configurações › API e integrações. A revogação vale na hora e não pode ser desfeita.

> **Guarde a chave no servidor**
>
> Não coloque a chave em aplicativos, páginas web ou repositórios de código. Se ela vazar, revogue no painel e gere outra.
