# Autenticação

> Como autenticar suas requisições na API FiscalAPI.

URL: https://docs.fiscalapi.com.br/docs/getting-started/authentication


Todas as requisições aos endpoints da API requerem autenticação via API Key.

## ## Obtendo sua API Key

1. Acesse o [Dashboard](https://app.fiscalapi.com.br?utm_source=docs\&utm_medium=docs\&utm_campaign=authentication) e crie sua conta
2. Após o registro, sua API Key será gerada automaticamente
3. Copie a chave no formato `fapi_...` em **Chave API**

## ## Usando a API Key

Envie sua chave no header `X-API-Key` em toda requisição:

```bash
curl -X GET "https://api.fiscalapi.com.br/api/consultar?uf=MT&cpf=12345678909" \
  -H "X-API-Key: fapi_sua_chave_aqui"
```

## ## Várias chaves por conta

Você pode ter mais de uma API Key na mesma conta, cada uma com um nome (por exemplo, `ERP`, `Planilha`, `Site`). Assim cada sistema usa a sua chave e você troca uma sem mexer nas outras.

* **Criar:** no Dashboard, em **Chave API**, dê um nome à chave. A chave inteira aparece **uma única vez**, na criação. Copie e guarde num lugar seguro; depois disso o Dashboard mostra só o começo dela (`fapi_ab12...`) para você reconhecer. Chaves criadas antes de existirem várias chaves por conta aparecem como **Oculta**, porque o começo delas nunca foi guardado.
* **Revogar:** revogue a chave de um sistema sem afetar as outras. A chave revogada ou substituída para de funcionar na hora e passa a receber `403` com `API key revoked` ou `Invalid API key`.
* **Consumo por chave:** o Dashboard mostra os créditos do mês de cada chave, e o histórico de consultas indica qual chave fez cada chamada.
* **Chave principal:** a chave que a conta já tinha é a principal. Regenerar a chave no Dashboard ou redefinir a senha troca **só a principal**; as outras continuam ativas.
* **Limite de chaves:** cada plano tem um número máximo de chaves ativas. Veja [Planos e Limites](/docs/referencia/plans-and-limits).

Créditos e limite de requisições por minuto são da **conta**: todas as chaves usam o mesmo saldo e o mesmo limite.

Para testar a integração sem gastar créditos, use uma chave de homologação (`fapi_test_...`), que responde com dados fictícios. Veja [Homologação](/docs/getting-started/homologacao).

## ## Login do painel

Integrações autenticam com a API Key. O login com e-mail e senha (ou Google/GitHub) serve só para o painel web: a sessão fica em cookies do navegador e não gera token para usar no seu sistema.

## ## Segurança

<Callout type="warn">
  Nunca exponha sua API Key no frontend ou em repositórios públicos. Use variáveis de ambiente no servidor.
</Callout>

* Requisições sem API Key, com chave inválida ou com chave revogada retornam `403 Forbidden` com o código `API_KEY_ERROR`
* Chave válida usada em um endpoint ao qual ela não tem acesso (a chave demo só consulta `/api/consultar`) retorna `403 Forbidden` com o código `ACESSO_NEGADO`

## ## Erro de autenticação

A resposta segue o formato de [Tratamento de Erros](/docs/referencia/error-handling). O campo `title` traz o código e o `detail` indica o motivo:

| `title`         | `detail`                                 | Quando acontece                                                                             |
| --------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------- |
| `API_KEY_ERROR` | `API key missing`                        | O header `X-API-Key` não foi enviado.                                                       |
| `API_KEY_ERROR` | `Invalid API key`                        | A chave enviada não existe (digitada errada, por exemplo) ou foi substituída no Dashboard.  |
| `API_KEY_ERROR` | `API key revoked`                        | A chave foi revogada ou substituída no Dashboard, ou a conta dona da chave está desativada. |
| `ACESSO_NEGADO` | `Chave demo restrita a rota de consulta` | A chave é válida, mas é uma chave demo, que só acessa `/api/consultar`.                     |

Os dois códigos usam o status 403: diferencie pelo `title`. Só `API_KEY_ERROR` indica chave inválida.

```json
{
  "type": "urn:fiscalapi:error:api_key_error",
  "title": "API_KEY_ERROR",
  "status": 403,
  "detail": "Invalid API key",
  "instance": "https://api.fiscalapi.com.br/api/consultar?uf=MT&cpf=12345678909",
  "request_id": "",
  "timestamp": "2026-10-20T10:30:00+00:00"
}
```