# Autenticação

A API do Festero usa o fluxo **client credentials** do OAuth 2.0, pensado para um sistema falando com os próprios dados, sem um usuário no meio. Você cria uma credencial no Festero, troca o `client_id` e o `client_secret` por um **token de acesso** e envia esse token em cada chamada.

```
credencial (client_id + client_secret)  ->  token de acesso (60 min)  ->  chamadas à API
```

## Criar a credencial

No Festero, abra **API do Festero** no menu lateral e clique em **Nova credencial**. Quem pode fazer isso, e por quê, está em [Introdução](https://developers.festero.com.br/introducao.md#quem-pode-criar-uma-credencial).

| Campo | Regra |
|---|---|
| Nome | Obrigatório, até 80 caracteres. Serve para você reconhecer a credencial. |
| Conjuntos de dados | Pelo menos um. Só aparecem liberados os que você mesmo enxerga no Festero. |
| Validade | 90 dias, renováveis. |

Depois de criar, o Festero mostra o `client_id`, o `client_secret`, o endpoint do token e o parâmetro `scope` pronto para uso.

> **Atenção**: Guarde o segredo agora
>
> O `client_secret` aparece **uma única vez**, na criação. Depois de fechar a janela, não é possível vê-lo de novo. Guarde-o num cofre de segredos ou numa variável de ambiente do servidor, nunca no código-fonte, num aplicativo de celular ou numa página web.

### Limites de credenciais

- Cada empresa pode ter até **5 credenciais** em uso (as que estão ativando, ativas ou suspensas).
- No máximo **10 credenciais criadas por hora** por empresa.

### Status de uma credencial

| Status na tela | O que significa |
|---|---|
| Ativando | Acabou de ser criada. Pode levar alguns minutos até funcionar. |
| Ativa | Pronta para uso. |
| Suspensa por plano | A empresa deixou de ter o plano Premium ou Enterprise. Volta ao normal quando o plano volta. |
| Revogada | Encerrada por uma pessoa. Não volta. |
| Expirada | Passou dos 90 dias sem renovação. Não volta. |

## Pedir o token

`$CLIENT_ID` e `$CLIENT_SECRET` são variáveis do seu terminal com os valores da credencial.

```bash
curl -X POST https://auth.festero.com.br/oauth2/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  -d "scope=festero-api/crm:read festero-api/events:read"
```

| Item | Valor |
|---|---|
| Método e endereço | `POST https://auth.festero.com.br/oauth2/token` |
| Autenticação | `Authorization: Basic <base64 de client_id:client_secret>` (o `-u` do `curl` já monta isso) |
| Tipo de conteúdo | `application/x-www-form-urlencoded` |
| `grant_type` | `client_credentials` |
| `scope` | Os escopos que a sua integração usa, separados por espaço, cada um no formato `festero-api/<escopo>` |

A resposta:

```json
{
  "access_token": "eyJraWQiOi...",
  "expires_in": 3600,
  "token_type": "Bearer"
}
```

`expires_in` é a validade em segundos: 3600, ou seja, **60 minutos**. Não há token de renovação nesse fluxo; quando o token vencer, peça outro do mesmo jeito. Exemplos completos em quatro linguagens estão no [Início rápido](https://developers.festero.com.br/inicio-rapido.md#_2-pedir-o-token).

## Usar o token

Envie o `access_token` em todas as chamadas, no cabeçalho `Authorization`:

```bash
curl https://platform.festero.com.br/v1/me \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Guardar o token pelos 60 minutos

> **Atenção**: Não peça um token a cada chamada
>
> Cada token emitido tem custo para o Festero, e o endpoint de token tem limite de uso. Um sistema que pede token a cada requisição acaba barrado pelo limite do endpoint de token.

O jeito certo:

1. Peça o token na primeira vez que precisar.
2. Guarde-o em memória (ou num cache compartilhado, se houver vários processos) junto com a hora de vencimento, calculada a partir de `expires_in`.
3. Reutilize-o em todas as chamadas.
4. Peça um novo cerca de 1 minuto antes de vencer, ou quando a API responder `401` [`token_invalid`](https://developers.festero.com.br/errors.md#token_invalid).

## Escopos

Os escopos dizem **quais dados** a credencial pode ler. Eles são definidos na criação da credencial.

| Escopo | No pedido do token | Dá acesso a |
|---|---|---|
| `crm:read` | `festero-api/crm:read` | [CRM](https://developers.festero.com.br/api/crm.md): oportunidades e etapas do funil |
| `visits:read` | `festero-api/visits:read` | [Visitas](https://developers.festero.com.br/api/visitas.md) |
| `events:read` | `festero-api/events:read` | [Eventos](https://developers.festero.com.br/api/eventos.md) |
| `quotes:read` | `festero-api/quotes:read` | [Orçamentos](https://developers.festero.com.br/api/orcamentos.md) |
| `finance:read` | `festero-api/finance:read` | [Financeiro](https://developers.festero.com.br/api/financeiro.md): recebíveis e resumo de vendas |

Pontos que costumam gerar dúvida:

- **O prefixo `festero-api/` só existe no pedido do token.** Na API, na tela e nas respostas (por exemplo em `GET /v1/me`), o escopo aparece sem prefixo, como `crm:read`.
- **O escopo que vale é o da credencial.** As rotas conferem os escopos concedidos à credencial no Festero. Se uma rota responde [`scope_missing`](https://developers.festero.com.br/errors.md#scope_missing), a credencial não tem aquele conjunto de dados. Para acrescentar um, crie uma credencial nova com o conjunto desejado; não é possível editar os escopos de uma credencial existente.
- **Peça no token só o que a integração usa.** Peça apenas escopos que a credencial possui.
- **Uma credencial nunca vê mais do que quem a criou.** Os conjuntos oferecidos na criação dependem das permissões da pessoa no Festero.
- `GET /v1/health` e `GET /v1/me` não pedem escopo. `GET /v1/me` aceita qualquer credencial válida.

## Renovar e rotacionar

| Ação (botão na tela) | O que faz |
|---|---|
| **Renovar** | Estende a validade por mais 90 dias, a partir de agora. O `client_id` e o segredo continuam os mesmos. |
| **Rotacionar** | Cria uma credencial **nova**, com o mesmo nome e os mesmos escopos, e mostra o novo `client_id` e o novo segredo. A antiga continua valendo por até **7 dias** ou até você revogá-la, o que vier primeiro. |
| **Revogar** | Encerra a credencial na hora. |

Para trocar o segredo sem derrubar a integração, rotacione, atualize o `client_id` e o segredo no seu sistema e depois revogue a credencial antiga. Durante a sobreposição, as duas contam no limite de 5 credenciais.

O Festero avisa as pessoas com a permissão de gerenciar a API quando uma credencial é criada, rotacionada ou revogada, e **7 dias antes** de uma credencial vencer.

## Revogar

Revogue uma credencial pelo botão **Revogar** do cartão dela. Para uma emergência (um segredo vazou, por exemplo), use **Revogar todas**.

A revogação vale em até **20 segundos**: depois disso, qualquer chamada com aquela credencial recebe `401` com o código [`credential_revoked`](https://developers.festero.com.br/errors.md#credential_revoked), mesmo que o token ainda esteja dentro dos 60 minutos. As chaves MCP ligadas à credencial deixam de funcionar junto.

## Erros de autenticação

| Código | HTTP | Causa | O que fazer |
|---|---|---|---|
| [`token_invalid`](https://developers.festero.com.br/errors.md#token_invalid) | 401 | Cabeçalho `Authorization` ausente ou malformado, token inválido ou **token vencido** (passou dos 60 minutos). | Envie `Authorization: Bearer <access_token>` com um token emitido pelo endpoint de token; se ele venceu, peça um novo. |
| [`credential_revoked`](https://developers.festero.com.br/errors.md#credential_revoked) | 401 ou 403 | Credencial revogada, suspensa, expirada ou ainda ativando. | Confira o status em **API do Festero** e crie ou renove a credencial. |
| [`plan_required`](https://developers.festero.com.br/errors.md#plan_required) | 403 | O plano da empresa não inclui a API. | A empresa precisa dos planos Premium ou Enterprise. |
| [`scope_missing`](https://developers.festero.com.br/errors.md#scope_missing) | 403 | A credencial não tem o conjunto de dados da rota. | Crie uma credencial com o escopo que falta. |

## Boas práticas de segurança

- Trate o `client_secret` como uma senha: variável de ambiente ou cofre, nunca no repositório.
- Use uma credencial por integração, com só os conjuntos de dados que ela precisa. Assim você revoga uma sem derrubar as outras.
- Chame a API sempre do **servidor**. Quem tem o segredo lê os dados da empresa; não o coloque em páginas web nem em aplicativos distribuídos.
- Renove ou rotacione antes dos 90 dias. As notificações do Festero avisam 7 dias antes.
- Se suspeitar de vazamento, revogue e crie outra credencial.