Autenticação e permissões

Token Bearer

Toda requisição leva o token no header Authorization:

curl -s "https://api.pegavez.com.br/api/salons/$SALON_ID/appointments?from=2026-11-03&to=2026-11-03" \
  -H "Authorization: Bearer pv_Zm9vYmFyYmF6cXV4..."

• O token tem o formato pv_ seguido de 32 bytes aleatórios em base64url (43 caracteres).
• Ele é mostrado uma única vez, na criação. O Pega Vez guarda só um hash e o prefixo (os 8 primeiros caracteres depois de pv_), que aparece na lista do painel para você saber qual é qual.
• Com Authorization: Bearer, a requisição autentica só pelo token: cookies são ignorados.
• Requisições com token não precisam do header X-Requested-With que o painel usa.

Host da API

Use sempre https://api.pegavez.com.br. Esse host aceita só token Bearer (cookie nunca autentica nele) e só encaminha:

Caminho	Para quê
/api/salons/{salonId}/...	API pública do salão do token
/mcp	servidor MCP
/health	verificação de disponibilidade (sem autenticação)

Qualquer outro caminho responde 404; um caminho de /api/ que não aceita token responde 401. O painel (pegavez.com.br) usa outro host, com sessão por cookie, e não é um endereço para integrações.

Onde o token vale

O token vale apenas:

• nas rotas /api/salons/{salonId}/... do próprio salão — outro salonId responde 404, como se o salão não existisse;
• no /mcp, onde o salão vem do próprio token.

Em qualquer outra rota — login, cadastro, conta (/me), troca de senha ou de e-mail, rotas públicas — uma requisição com token responde 401. Token desconhecido, expirado, revogado ou de membro desativado também responde 401, com o header WWW-Authenticate: Bearer.

Permissões: token × membro

O token é criado por um membro da equipe e age em nome dele, com um subconjunto das permissões dele.

1. Na criação, você escolhe as permissões do token entre as que você tem, com escopo igual ou menor. Não dá para dar ao token algo que você não pode fazer.
2. Em cada requisição, a permissão efetiva é a interseção entre o que o token tem e o que o membro tem agora (fica o menor escopo). Se o membro perder uma permissão, o token perde junto (403); se o membro for desativado, os tokens que ele criou são revogados de vez (401) — reativar o membro não os traz de volta.

Permissões com escopo seguem a mesma regra: se o membro só vê a própria agenda (agenda.view com escopo “próprio”), o token também só vê a agenda daquele profissional, e agendamentos dos outros respondem 404.

Permissões que a API e o MCP usam:

Permissão	Escopo	Permite
agenda.view	todos ou só o próprio	Ver a agenda, os horários livres e os profissionais
agenda.edit	todos ou só o próprio	Criar, remarcar e cancelar agendamentos; mudar o status; encaixes
customers.view	—	Ver clientes
customers.edit	—	Cadastrar e editar clientes; ver observações e nascimento
checkout.operate	—	Ver comandas (e saber se o caixa está aberto, no MCP)
cash.manage	—	Ver os valores do caixa aberto (só no MCP)
reports.view	—	Relatórios de faturamento e recebimentos

Listar e consultar serviços vale para qualquer membro, sem permissão específica. A permissão de cada endpoint está na lista de endpoints. Faltou permissão: 403, sem code. Veja Erros.

Permissões que um token nunca tem

• integrations.manage — criar e revogar tokens e gerenciar webhooks;
• billing.manage — assinatura e cobrança;
• staff.manage — membros da equipe e jornadas;
• roles.manage — perfis e permissões.

Tokens e webhooks são gerenciados só no painel, por um usuário logado. Assim, um token vazado não consegue criar outro token, apontar webhooks para outro endereço nem mexer na assinatura.

Expiração e revogação

• Validade: cada token tem uma data de expiração opcional (o padrão na tela é 1 ano). Depois dela, o token responde 401. Crie um token novo antes do vencimento e troque na integração.
• Revogação: em Configurações → Integrações, Revogar invalida o token na hora. Não há como desfazer. Revogar (e ver a lista) funciona mesmo depois de mudar para um plano sem integrações; desativar um membro revoga os tokens dele.
• Último uso: a lista mostra quando cada token foi usado pela última vez (atualizado no máximo uma vez por minuto). Token parado há meses é candidato a revogar.
• Limite: cada salão pode ter até 50 tokens ativos (nem revogados nem expirados).

Para trocar um token sem parar a integração: crie o novo, atualize a configuração, confirme que as chamadas passam e só então revogue o antigo.

Limite de requisições

Cada token pode fazer 600 requisições por minuto (janela fixa de 60 segundos, API e MCP somados). Acima disso a resposta é 429, com o header Retry-After dizendo quantos segundos esperar:

HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/problem+json

Espere o tempo indicado antes de tentar de novo. Se a integração precisa sincronizar muito volume, prefira webhooks a consultas repetidas.

Requisições com um token que não autentica (inválido, revogado, expirado ou de membro desativado) também têm limite: 60 por minuto por IP. Acima disso, 429 com Retry-After em vez de 401.

Boas práticas

• Um token por integração, com nome claro: dá para revogar um sem derrubar os outros.
• Só as permissões necessárias. Uma integração que só lê a agenda não precisa de agenda.edit.
• Crie o token com um usuário que vai continuar na equipe: se ele for desativado, o token é revogado.
• Guarde o token como segredo (cofre, variável de ambiente). Nunca em repositório, log, URL ou app do cliente.
• Suspeita de vazamento: revogue na hora e crie outro.