Autenticação

A API aceita duas credenciais em Authorization: Bearer. As duas chegam às mesmas regras do sistema, com o autor certo na trilha de auditoria.

	Chave do app	OAuth da pessoa
Formato	`wx_` + 64 caracteres hexadecimais	token de acesso emitido pelo servidor de autorização da Westhetics
Quem é	o app de integração, uma identidade da clínica	a pessoa que entrou e autorizou, com o perfil dela na clínica
O que pode	o que os escopos do app liberam	o que o perfil da pessoa pode no sistema, nas áreas abertas à integração
Quanto dura	até a gestora revogar ou regenerar	a sessão de 12 horas da pessoa; depois, ela conecta de novo
Para quê	CRM, automação, sistema próprio da clínica, scripts	apps de parceiro com “Conectar com a Westhetics” e assistentes de IA pelo MCP

A chave do app

GET /v1/me HTTP/1.1
Host: api.westhetics.io
Authorization: Bearer wx_1c0a58f5e2b7c9d4a6f1032e8b7c5d4a9f0e1b2c3d4e5f60718293a4b5c6d7e8f

Quem cria. A gestora da clínica, em Integrações no painel (app.westhetics.io/admin/integrations). Cada clínica tem até 10 apps ativos.
Uma clínica. A chave vale só para a clínica do app: nunca para outra, nem para as clínicas da mesma rede.
Mostrada uma vez. A Westhetics guarda só o hash SHA-256 e os 8 primeiros caracteres depois do wx_, que a tela mostra (“chave wx_1c0a58f5…”). Quem perde a chave regenera.
Conferida a cada chamada. Sem cache: revogar vale na chamada seguinte, em qualquer servidor.

Trate a chave como senha. Ela fica no servidor, num cofre de segredos ou numa variável de ambiente. Nunca no navegador, no app do celular, em planilha nem no repositório. Um vazamento se resolve regenerando ou revogando a chave em Integrações.

Regenerar sem queda

Regenerar pede uma justificativa e gera uma chave nova na hora. A anterior continua aceita por 15 minutos, para você trocar sem derrubar a integração. Nesse intervalo, toda resposta a uma chamada com a chave anterior traz o cabeçalho:

X-Westhetics-Notice: previous-key; valid-until=2026-10-15T14:50:00Z

Se o seu log mostrar esse cabeçalho, o servidor ainda está com a chave antiga. As gestoras da clínica recebem um e-mail a cada regeneração.

Revogar

Revogar é definitivo e vale na chamada seguinte: toda chamada com a chave passa a responder 401. As entregas de webhook que estavam na fila do app não saem mais. O app revogado não volta; cria-se outro.

Escopos

Cada app tem pelo menos um escopo. Escrever um recurso inclui ler o mesmo recurso. As respostas da anamnese pedem o escopo próprio, mesmo com anamneses:write.

Escopo	Na tela	O que libera
`patients:read`	Pacientes · Ler	Listar, buscar e ler pacientes; os eventos `patient.*`.
`patients:write`	Pacientes · Ler e escrever	Criar e editar pacientes. Inclui ler.
`anamneses:read`	Anamneses · Ler	Listar e ler anamneses, sem as respostas; os eventos `anamnesis.*`.
`anamneses:write`	Anamneses · Ler e escrever	Enviar, reenviar e cancelar anamnese. Inclui ler.
`anamneses:answers`	Ler as respostas da anamnese	Ler as respostas da anamnese preenchida. É dado de saúde.
`documents:read`	Documentos e assinaturas · Ler	Atendimentos, documentos, status da assinatura e o PDF; os eventos `appointment.` e `signature_request.`.
`documents:write`	Documentos e assinaturas · Ler e escrever	Gerar contrato e termos e enviar para assinatura, reenviar e cancelar. Inclui ler.
`catalog:read`	Catálogo · Ler	Procedimentos, prestadores e modelos de documento da clínica.
`webhooks:write`	Gerenciar os próprios webhooks pela API	Criar, alterar e remover os webhooks do próprio app pela API.

A gestora muda os escopos na tela do app, e a mudança vale na chamada seguinte. Chamada fora dos escopos responde 403 com o nome da permissão que falta:

{
  "error": {
    "code": "forbidden",
    "message": "O app \"CRM da recepção\" não tem a permissão \"Documentos e assinaturas · Ler e escrever\". A gestora inclui em Integrações, na Westhetics.",
    "requestId": "2730cba1-4431-4c10-a8f7-86458080df06"
  }
}

O que o app nunca faz

Mesmo com todos os escopos, o app de integração tem, nas regras, o que a recepção tem: ele não arquiva nem unifica paciente, não exporta, não lê faturamento, não administra a clínica, não assina como responsável e não exclui documento. Fotos do plano de tratamento, links de assinatura e dados de outra clínica nunca saem pela API.

OAuth da pessoa

O OAuth serve para quem age em nome de uma pessoa da clínica: um app de parceiro com o botão “Conectar com a Westhetics” e os assistentes de IA. A pessoa entra com a conta dela, vê a tela Conectar o à sua conta? e autoriza. O token que o seu app recebe:

age com o perfil da pessoa (recepção, prestador, gestora), na clínica da conexão;
lê e escreve o que este portal documenta (pacientes, anamnese, contrato, pendências), nada de administração;
vale as 12 horas da sessão; depois, a pessoa conecta de novo;
entra na trilha como a própria pessoa, com o aplicativo registrado junto.

O servidor de autorização segue o OAuth 2.1 com PKCE (S256) e aceita o registro dinâmico de cliente (RFC 7591). É o mesmo do MCP, e o endereço dele está nos metadados do recurso protegido:

curl https://mcp.westhetics.io/.well-known/oauth-protected-resource

O caminho completo, passo a passo, está em MCP › segurança e privacidade e no guia de cada assistente.

A sessão do painel da Westhetics (o token do navegador) não vale na API pública. Use a chave de um app ou um token OAuth.

Começar

Guias

Como a API funciona

A chave do app

Regenerar sem queda

Revogar

Escopos

O que o app nunca faz

OAuth da pessoa