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.

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.

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.

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:

{
  "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.

Usar o token

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

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

Guardar o token pelos 60 minutos

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 token_expired.

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: oportunidades e etapas do funil
visits:read	festero-api/visits:read	Visitas
events:read	festero-api/events:read	Eventos
quotes:read	festero-api/quotes:read	Orçamentos
finance:read	festero-api/finance:read	Financeiro: 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, 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, 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	401	Cabeçalho Authorization ausente ou malformado, ou token inválido.	Envie Authorization: Bearer <access_token> com um token emitido pelo endpoint de token.
token_expired	403	O token passou dos 60 minutos.	Peça um token novo.
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	403	O plano da empresa não inclui a API.	A empresa precisa dos planos Premium ou Enterprise.
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.