# Autenticação e chaves

> Como autenticar na API do FORSI Chat: chave Bearer, escopos, validade, lista de IPs, troca de chave sem parar o sistema e os erros 401, 403 e 429.

A API reconhece quem chama por uma chave secreta, enviada em toda requisição no cabeçalho `Authorization: Bearer <chave>`. Cada chave pertence a uma organização e só faz o que os seus escopos permitem.

```bash title="terminal"
curl "https://chat.forsi.com.br/api/v1/me" -H "Authorization: Bearer $FORSI_CHAVE"
```

A chave tem o formato `fcv2_live_<id>_<segredo>` (nos exemplos, `fcv2_live_EXAMPLE`). Guardamos só um resumo (sha256) e não temos como mostrar a chave de novo: perdeu, crie outra.

## Criar uma chave

1. Entre como dono ou gestor em **Configurações → API e webhooks** e toque em **Nova chave**.
2. Dê um nome que diga qual integração vai usar a chave (`ERP`, `site`, `n8n`) e marque só os escopos de que ela precisa.
3. Se quiser, defina a validade e a lista de IPs que podem usar a chave.
4. Copie a chave na hora e guarde no cofre de segredos ou numa variável de ambiente do servidor. Ela não aparece de novo.

## O que a API confere em cada chamada

> **Figura: O que a API confere em cada chamada.** O seu servidor manda Authorization: Bearer fcv2_live_... . Primeiro a API exige https e recusa chamadas com cabeçalho Origin, vindas de navegador (403). Depois confere a chave: existe, não foi revogada, não venceu e o IP está na lista (senão, 401 nao_autorizado, sempre igual). Em seguida o plano e a assinatura (403 modulo_fora_do_plano ou assinatura_bloqueada), o escopo da rota (403 escopo_insuficiente) e o limite por minuto (429 com Retry-After). Passou em tudo: a resposta sai com 2xx e {"dados": ...}.

A conferência segue esta ordem, e a primeira que falhar responde:

| Ordem | O que confere | Se falhar |
| --- | --- | --- |
| 1 | Conexão https | `403 https_obrigatorio` |
| 2 | Sem cabeçalho `Origin` (a chamada não vem de navegador) | `403 origem_nao_permitida` |
| 3 | A chave existe, não foi revogada, não venceu e o IP está na lista | `401 nao_autorizado`, sempre igual, sem dizer o motivo |
| 4 | Plano com o módulo API e assinatura em dia | `403 modulo_fora_do_plano` ou `403 assinatura_bloqueada` |
| 5 | Escopo da rota | `403 escopo_insuficiente` (o escopo que faltou vem em `detalhe`) |
| 6 | Limite por minuto | `429 limite_excedido`, com `Retry-After` |

Muitas tentativas com chave errada do mesmo endereço bloqueiam esse endereço por alguns minutos: `429 muitas_falhas`, com `Retry-After`.

## Escopos, validade e IPs

- Cada chave tem **escopos** (o que pode fazer; veja [Escopos e planos](https://docs.forsi.com.br/escopos)). Peça só os que a integração usa.
- A chave pode ter **validade** (vence sozinha) e uma **lista de IPs** permitidos.
- Revogar corta na hora.

## Trocar a chave sem parar o sistema

Use **Trocar a chave**: sai uma chave nova e a antiga continua valendo pelo tempo que você escolher (até 7 dias). Coloque a nova no servidor, confira que as chamadas passam e deixe a antiga vencer.

## Quem sou eu

[`GET /me`](https://docs.forsi.com.br/api/conta/me) aceita qualquer chave válida e mostra a organização, os escopos e a validade da chave, os limites da organização e as caixas (WhatsApps) com o estado da conexão. É a melhor primeira chamada para conferir a configuração.

## Perguntas frequentes

### Perdi a chave. Dá para ver de novo?

Não. Guardamos só um resumo (sha256), que não permite recuperar o texto da chave. Crie outra e revogue a perdida.

### Por que o 401 não diz o motivo?

De propósito. Chave ausente, errada, revogada, vencida ou fora da lista de IPs recebem a mesma resposta, para não ajudar quem tenta adivinhar chaves. Confira no app se a chave está ativa, se não venceu e se o IP do seu servidor está na lista.

### Posso usar a mesma chave em duas integrações?

Pode, mas não é bom. Com uma chave por integração dá para revogar uma sem parar a outra, e a auditoria mostra o nome da chave que fez cada mudança.

### A chave vale para outra organização?

Não. Cada chave pertence a uma organização. Ids de outra organização respondem `404`, como se não existissem.

## Endpoints de Conta

- [`GET /me`](https://docs.forsi.com.br/api/conta/me): Quem sou eu

---

Página: https://docs.forsi.com.br/autenticacao · Índice: https://docs.forsi.com.br/llms.txt · Tudo num arquivo: https://docs.forsi.com.br/llms-full.txt