# Autenticação

Toda chamada à API precisa de uma **chave de API** da sua conta. A chave começa com `pf_live_` e tem 40 caracteres.

## Como enviar

O jeito recomendado é o cabeçalho `Authorization` com o esquema `Bearer`:

```http
GET /v1/placas/ABC1D23 HTTP/1.1
Host: api.placaefipe.com.br
Authorization: Bearer pf_live_sua_chave_aqui
```

Também aceitamos o cabeçalho `X-API-Key`, útil em ferramentas que não deixam editar o `Authorization`:

```http
X-API-Key: pf_live_sua_chave_aqui
```

A chave **não** é aceita na URL (query string), para não vazar em logs e no histórico do navegador.

## Chaves de produção e de teste

| Tipo | Começa com | O que faz | Custo |
|---|---|---|---|
| Produção | `pf_live_` | Consulta real no registro do veículo e FIPE do mês | 1 crédito por placa encontrada |
| Teste | `pf_test_` | Devolve um veículo de exemplo com a placa pedida, sem consultar nada | Grátis |

Use a chave de teste no desenvolvimento, em testes automatizados e quando uma IA estiver integrando o seu projeto. Na chave de teste, a placa `AAA0000` simula "não encontrada" (404).

## Limite mensal por chave

Ao criar uma chave de produção no painel, você pode definir um **limite de créditos por mês**. Quando a chave chega ao limite, ela para de consultar (erro `limite_da_chave`) até o mês virar ou você aumentar o limite. Assim, se uma chave vazar, o estrago fica limitado ao teto que você escolheu.

## Como seus créditos ficam protegidos

- Cada conta tem as próprias chaves. Uma chave só gasta os créditos da conta dona dela.
- Guardamos só o hash da chave. Nem a nossa equipe consegue ver a chave inteira depois de criada.
- Você vê o último uso e o consumo do mês de cada chave no painel, e revoga qualquer uma na hora.

## Onde guardar

| Ambiente | Onde colocar `PLACAEFIPE_API_KEY` |
|---|---|
| Vercel | Settings → Environment Variables |
| Netlify | Site configuration → Environment variables |
| Supabase Edge Functions | `supabase secrets set PLACAEFIPE_API_KEY=...` |
| Cloudflare Workers | `wrangler secret put PLACAEFIPE_API_KEY` |
| Railway / Render / Fly.io | Variáveis do serviço |
| Local | `.env.local` (fora do git) |

## Regras de segurança

- A chave dá acesso aos **seus créditos**. Trate como senha.
- Use a chave **só no servidor**. Se o seu app é só front-end (React, Vue, Flutter, Lovable), crie uma rota de API ou edge function que chama o Placa & FIPE e devolve o resultado para a tela.
- Crie **uma chave por projeto** (planos Pro e Escala). Assim você vê o consumo de cada um e pode revogar só a que vazou.

## Trocar a chave sem parar o sistema

1. Gere uma chave nova no [painel](https://placaefipe.com.br/painel).
2. Atualize a variável de ambiente e faça o deploy.
3. Revogue a chave antiga no painel. A revogação vale na hora.

## Erros de autenticação

| HTTP | `erro.codigo` | Causa |
|---|---|---|
| 401 | `nao_autenticado` | Nenhuma chave enviada |
| 401 | `chave_invalida` | Chave errada, incompleta ou revogada |

Veja todos os códigos em [Erros](/docs/erros).