---
title: "Autenticação e ambientes da Captura Fiscal"
description: "Como autenticar na API de recepção automática: API Key no header Authorization, ambientes de produção/homologação e o campo environmentSEFAZ."
source_url: https://nfe.io/docs/distribuicao-comum-autenticacao/
last_updated: 2026-07-30
---

# Autenticação e ambientes da Captura Fiscal

A API de recepção automática aceita **dois métodos de autenticação** e separa o ambiente da plataforma do ambiente da SEFAZ.

## API Key

O método mais comum. Envie a sua chave no header **`Authorization`**:

```http
GET /v2/companies/{companyId}/inbound/nfse HTTP/1.1
Host: api.nfse.io
Authorization: ApiKey SUA_API_KEY
```

:::caution Não use o prefixo `Bearer`
Qualquer prefixo antes de um espaço é aceito e descartado (`ApiKey `, `Token `, ou nenhum) — a chave em si é o que importa. A única exceção é `Bearer `: esse prefixo é tratado como um token de plataforma, não como API Key, e a autenticação falha.
:::

A chave pode ser enviada de três formas equivalentes:

| Forma | Exemplo |
|---|---|
| Header `Authorization` | `Authorization: ApiKey SUA_API_KEY` |
| Header `X-NFEIO-APIKEY` | `X-NFEIO-APIKEY: SUA_API_KEY` |
| Query string `api_key` | `?api_key=SUA_API_KEY` |

A API Key é gerenciada no painel da empresa (em **Chaves de API**).

Cada endpoint de recepção é protegido por uma *policy* (`NFeDist`, `CTeDist` ou `NFSeDist`, conforme o documento), e **cada policy aceita dois papéis de API Key**:

| Policy do endpoint | Papéis de API Key aceitos |
|---|---|
| `NFeDist` | `Nota Fiscal (api.nfe.io)` **ou** `NFeDist (dfe.nfe.io)` |
| `CTeDist` | `Nota Fiscal (api.nfe.io)` **ou** `CTeDist (dfe.nfe.io)` |
| `NFSeDist` | `Nota Fiscal (api.nfe.io)` **ou** `NFSeDist (dfe.nfe.io)` |

Ou seja: uma API Key com o papel geral **`Nota Fiscal (api.nfe.io)`** — que a maioria das chaves já possui — autentica os três produtos de recepção. Os papéis específicos (`NFeDist`/`CTeDist`/`NFSeDist (dfe.nfe.io)`) existem para chaves **restritas** a um único produto (princípio do menor privilégio).

:::note Inbound usa apenas API Key
Os endpoints de recepção (NF-e, CT-e, NFS-e) são protegidos **exclusivamente** pelo esquema de **API Key** (confirmado no código — os controllers usam `ApiKeyDefaults.AuthenticationScheme`). Um token Bearer de plataforma **não** autentica esses endpoints (retorna `401`).
:::

## Papéis (roles)

Os endpoints de **manutenção administrativa** da NFS-e (`fetch-now`, `notifications`, `statistics`, `reactivate`) exigem o papel **`Management`** — chamadas sem ele retornam `403`.

## Ambientes

Há **duas noções de ambiente** que não devem ser confundidas:

| Noção | O que controla | Como é definido |
|---|---|---|
| **Ambiente da plataforma** | Produção × Homologação da NFE.io | Mesmo host `api.nfse.io`; selecionado pela API Key |
| **Ambiente da SEFAZ** | Validade fiscal dos documentos capturados | Campo **`environmentSEFAZ`** na ativação |

### O campo `environmentSEFAZ`

Na ativação da captura, `environmentSEFAZ` indica o ambiente da SEFAZ:

```json
{
  "startFromDate": "2026-06-01T00:00:00Z",
  "environmentSEFAZ": "Production"
}
```

- Valores aceitos: **`"Production"`** (produção, validade fiscal real) e **`"Test"`** (homologação, sem validade fiscal).
- Internamente mapeiam para `1 = Produção` e `2 = Homologação`.
- Quando omitido, o padrão é **`Test`** (homologação).

## Veja também

- [AN × ADN](./an-vs-adn.md)
- [Ativar via API (NF-e/CT-e)](../nfe-cte/index.md)
- [Integração REST (NFS-e)](../nfse-inbound/how-to/integracao-rest.md)