Chaves, escopos e agentes

Há duas formas de chamar o Brasil Sintético. As duas valem para um projeto e passam pelas mesmas regras e pelo mesmo limite de chamadas.

Quem chama	Como se identifica	Onde funciona
Um programa seu	Uma chave de API do projeto	API (/v1) e servidor MCP
Um agente de IA com navegador (Claude, ChatGPT, Cursor, VS Code)	Login OAuth no app, com consentimento	Servidor MCP

Chaves de API

• Criadas na página do projeto por quem é admin ou dono dele.
• A forma é bs_<prefixo>_<segredo>, enviada como Authorization: Bearer bs_….
• A chave aparece uma única vez. Guardamos só o hash dela; quem perde a chave cria outra.
• Uma chave pode expirar sozinha em 7, 30, 90 ou 365 dias, escolhidos na criação, ou não expirar.
• Trocar uma chave cria outra com o mesmo nome, os mesmos escopos e a mesma duração. A antiga para na hora, ou depois de uma carência de 1 ou 7 dias, para os sistemas que a usam passarem à nova.
• Revogar é imediato. Arquivar o projeto desliga todas as chaves dele e o acesso dos agentes conectados; restaurar o projeto devolve os dois.
• O app pede confirmação antes de trocar, revogar, desconectar ou arquivar.
• A página do projeto mostra o último uso de cada chave.

Escopos

Escopo	Permite
results:read	Ler jobs, achados e cidades: GET /v1/whoami, GET /v1/jobs, GET /v1/jobs/{id}, GET /v1/jobs/{id}/findings; no MCP, as ferramentas que só leem (Ferramentas do MCP), como list_releases, get_job, get_findings, get_answers, get_calibration e get_city_diagnosis.
simulate	Gastar créditos e mudar o projeto: POST /v1/jobs/estimate, POST /v1/jobs, POST /v1/jobs/{id}/cancel; no MCP, estimate_simulation, submit_simulation, cancel_job, erase_job_data, estimate_calibration, submit_calibration e open_city_diagnosis.
calibrate	Reservado. A calibração com dados do cliente já está disponível e usa simulate.
manage	Reservado; só para chaves, nunca concedido a agentes.

Uma chamada sem o escopo necessário é recusada com 403 missing_scope na API e com insufficient_scope no MCP.

Agentes com login (OAuth)

O servidor MCP segue a especificação de autorização do MCP:

• OAuth 2.1 com PKCE;
• metadados do servidor de autorização e do recurso protegido (RFC 8414 e RFC 9728);
• registro de clientes por documento de metadados (CIMD) ou registro dinâmico (DCR);
• o iss na resposta de autorização (RFC 9207).

Você não precisa configurar nada disso. Basta colar a URL do servidor no agente (Conectar um agente).

O que acontece no login:

1. O agente abre o app no navegador. Você entra na sua conta, ou cria uma ali mesmo, só com nome, e-mail e senha; depois de confirmar o e-mail e entrar, o app volta ao pedido do agente, se ele ainda valer (ele vale por 10 minutos).
2. Você escolhe um projeto e o que o agente pode fazer. Uma conta nova já tem um primeiro projeto para isso. Quem é só leitor do projeto concede apenas results:read; simulate exige ser membro, porque gasta créditos.
3. O agente recebe tokens só para aquele projeto:
   • o token de acesso vale 1 hora;
   • o de renovação vale 90 dias e muda a cada uso.

Os agentes conectados aparecem na página do projeto, em Agentes conectados. Quem conectou um agente pode desconectá-lo; admins e donos podem desconectar qualquer um. Desconectar invalida os tokens na hora. Cada token também é conferido contra o seu papel atual: quem sai da organização leva junto o poder dos agentes que conectou.

Agentes sem navegador

Um agente que roda num servidor, sem navegador para o login, usa uma chave de API do projeto no cabeçalho Authorization da conexão MCP. As ferramentas respeitam os escopos da chave.

Apagar um projeto, a organização ou a conta

• Um projeto: um admin ou dono abre o projeto no app e usa Apagar o projeto, digitando o nome dele. Na hora, o projeto sai das listas, as chaves param e os agentes conectados perdem o acesso. Durante 7 dias, um admin ou dono desfaz em Projetos → Exclusões pedidas. Depois disso, a plataforma apaga para sempre os dados dos jobs, as bases de clientes, os documentos, as conversas, os webhooks, as chaves e as autorizações de agentes. Fica só o registro de cada job, com os hashes.
• A organização: só um dono pede, em Membros → Apagar a organização, digitando o nome dela. Ela fecha na hora para todos, com os mesmos 7 dias para desfazer. Depois, todos os projetos, os membros e os convites são apagados. O extrato de créditos, as compras e os dados das notas fiscais ficam guardados pelo prazo da lei fiscal. O saldo livre pode ser devolvido a pedido, pela regra do estorno.
• A sua conta: em Perfil → Apagar a conta, com a sua senha. Ela sai na hora; o que você criou nos projetos fica com eles. Se você for o único dono de uma organização, nomeie outro dono, ou peça para apagar a organização, antes.
• Os donos e admins recebem um e-mail a cada pedido e a cada desfazer.
• Nenhum agente conectado apaga um projeto ou a organização: só uma pessoa, no app.