Contas de serviço

Uma conta de serviço é uma conta de sistema da instituição, usada por integrações: um ERP que sincroniza cursos, um script que abre tickets, um agente de IA que opera o painel sem uma pessoa por trás. Ela recebe papéis como um membro e acessa o Workfuse por tokens, nunca por login.

A conta faz o que os papéis dela permitem, nada além. Tudo o que ela altera aparece no histórico com o nome da conta e a instituição dela.

Conta de serviço, chave de API ou MCP?

	Conta de serviço	Chave de API	MCP
Para quem	Integrações que precisam do painel ou da API pública com um papel	Integrações que só usam a API pública	Pessoas que usam um cliente de IA
Como autentica	Token da conta, em cada requisição	Chave, em cada requisição	Login da pessoa, no navegador
Com que permissão age	A dos papéis da conta, lida a cada pedido	A dos módulos marcados na chave	A do papel da pessoa
Onde vale	API do painel, cliente de IA e API pública, conforme o token	API pública	Cliente de IA
Quem aparece no histórico	A conta, com a instituição	Nenhuma pessoa	A pessoa, "via" o cliente de IA

A chave de API continua funcionando como sempre. A conta de serviço é para quem precisa de mais do que a API pública, ou de um papel em vez de módulos.

Antes de começar

• Quem cria contas é quem tem a permissão de gerenciar contas de serviço na instituição. O papel Admin tem essa permissão.
• A conta é de uma instituição. Ela alcança o que o papel dela alcança nessa instituição, como um membro com o mesmo papel. O Admin dado na instituição não inclui os módulos da organização (Contatos, Negócios, Pipelines, Estrutura física e Organização); um papel que marca o módulo inclui.
• A conta nunca é super admin e não entra no painel por login.

Criar uma conta

1. Abra Configurações › Instituições e escolha a instituição.
2. Na aba Contas de serviço, clique em Nova conta.
3. Dê um nome à conta, por exemplo "Integração ERP". O nome é único na instituição.
4. Escolha os papéis. Eles seguem as mesmas regras dos membros: só um Admin dá o papel Admin.

Para mudar os papéis depois, use Editar papéis. A mudança vale no pedido seguinte da integração.

Gerar um token

1. Na conta, clique em Novo token.
2. Dê um nome ao token, por exemplo "produção".
3. Marque onde ele vale:
   • API do painel: as mesmas operações do painel, pela API.
   • Cliente de IA: o MCP do painel, para um agente de IA como o Claude Code.
   • API pública: as rotas públicas, como o envio de redações para correção.
4. Escolha a validade: 30, 90 ou 365 dias, ou sem expiração.
5. Copie o token. Ele aparece uma vez só: depois, a lista mostra só o nome e os quatro últimos caracteres.

Uma conta pode ter vários tokens, por exemplo um por ambiente. Revogar um não afeta os outros.

Usar o token

Envie o token no cabeçalho Authorization de cada requisição:

Authorization: Bearer wfs_...

• API do painel (https://api.workfuse.com/api/v1): a organização e a instituição são as da conta, e os cabeçalhos de organização e de instituição são opcionais. Quando vierem, precisam ser os da conta. Uma operação por instituição pede o cabeçalho x-institution-id com a instituição da conta.
• Cliente de IA (https://api.workfuse.com/mcp/platform): configure o token como o Bearer do servidor MCP no cliente. As operações oferecidas são as mesmas da conexão por login. Criar chaves, convidar membros, editar papéis e gerenciar contas nunca são oferecidos.
• API pública (https://api.workfuse.com/public/v1): o papel da conta precisa da permissão de API pública do módulo (correção de redação, CRM ou processo seletivo), e o módulo precisa estar contratado.

Pedido sobre dado de outra instituição ou de outra organização responde como não encontrado.

Limite de uso

Cada token aceita 120 pedidos por minuto, somando as três superfícies. O pedido acima do limite recebe o status 429 e o cabeçalho Retry-After com os segundos até a janela de um minuto terminar.

Revogar e desligar

• Revogar um token encerra só aquele token. Os outros tokens da conta seguem valendo.
• Desligar a conta revoga todos os tokens dela de vez. A conta pode ser religada, mas precisa de tokens novos.
• A equipe Workfuse também pode revogar um token ou desligar uma conta, um de cada vez.

Um token vencido, revogado ou de conta desligada recebe a mesma recusa de credencial inválida, com o status 401.

O que a conta não é

• Não é membro. Ela não aparece na lista de Membros, não pode ser escolhida como responsável ou atendente e não conta como Admin da instituição.
• Não aprova clientes de IA. Para usar um agente de IA, configure o token direto no cliente.
• Não é excluída. Uma conta que não se usa mais é desligada, e o histórico dela fica.