Autenticação

A API do Workfuse usa API keys por instituição. Cada requisição leva a chave no header Authorization, no formato Bearer:

Authorization: Bearer wf_sua_chave_aqui

Chave de API ou MCP?

A chave de API é para a API pública e para integrações entre sistemas: não há uma pessoa por trás dela. Para conectar um cliente de IA (Claude, Cursor e afins) ao painel, com o login e as permissões de uma pessoa, o caminho é o MCP, e uma chave de API nunca o conecta.

Passo a passo do MCP em Conectar clientes de IA (MCP).

Token de conta de serviço

Uma integração que precisa de papel, como um membro, usa o token de uma conta de serviço (prefixo wfs_), no mesmo header:

Authorization: Bearer wfs_seu_token_aqui

Na API pública o token precisa da superfície API pública e, no papel da conta, da permissão do módulo chamado. A instituição é a da conta. Token inválido, expirado ou revogado responde 401; sem a permissão, 403; acima de 120 pedidos por minuto por token, 429 com Retry-After.

Como criar a conta e gerar o token em Contas de serviço.

Gerar uma chave

No painel, vá em Configurações → API Keys (requer perfil de administrador) e crie uma chave. Você escolhe a instituição, dá um nome e marca os módulos que ela alcança.

A chave em claro (prefixo wf_) é exibida uma única vez, no momento da criação — copie e guarde com segurança; não é possível vê-la de novo.

Escopo

Cada chave:

• pertence a uma instituição da sua organização — você só acessa os dados daquela instituição, e não informa a organização nem a instituição no corpo das requisições;
• tem escopo por módulo — só acessa os módulos marcados na criação. Chamar um endpoint de um módulo fora do escopo retorna 403.

Integração	Módulo a marcar
Processo Seletivo	Captação & Processo seletivo · Processo seletivo (admission.selection) — a chave alcança a jornada inteira, inscrição completa incluída (nome, e-mail, telefone, nascimento, CPF e respostas, de qualquer candidato da instituição); guarde-a como guarda uma senha de banco
Correção de Redação	Ensino · Correção (correction)

Use o princípio do menor privilégio: uma chave por integração, só com os módulos que ela precisa.

Revogar e rotacionar

Em Configurações → API Keys você pode revogar uma chave a qualquer momento (ela para de funcionar imediatamente). Para rotacionar, crie uma nova chave, atualize a integração e revogue a antiga.

Erros de autenticação

HTTP	Significado
401	header Authorization ausente, malformado, ou chave inválida/revogada
403	chave válida, mas sem o módulo necessário no escopo