Tokens
Três prefixos, três funções. O token carrega o tenant. Não invente um header de tenant.
| Prefixo | Emitido por | Fala com | Exemplo de uso |
|---|---|---|---|
vb_agent_… | valorbrain init --agent → POST /api/v1/agents/signup | REST em valorbrain-api | CLI add / search |
vbm_… | App → Settings → tokens MCP, ou OAuth | MCP em mcpbrain | MCP no editor, @valorbrain/connect |
fk_….sk_… | App → API keys | SaaS POST /api/v1/ingest (e algumas rotas do SaaS) | Sistemas externos empurrando documentos |
Eles não são intercambiáveis. Uma chave vb_agent_ no mcpbrain é a
audience errada. Um token vbm_ é o que o card do servidor MCP anuncia
(tokenPrefix: "vbm_").
O tenant está no token
A CLI não envia X-Tenant-ID. O engine resolve o tenant a partir do bearer
token e expõe o resultado como X-Resolved-Tenant-ID.
Não invente um UUID de tenant. Não copie um de tutorial.
Páginas antigas no /docs de marketing mostravam exemplos REST com
Authorization: Bearer vb_… e X-Tenant-ID. Esse header não é
necessário para uma chave com escopo de tenant, e o prefixo é vb_agent_,
não um vb_ solto.
Escopos
Tokens MCP têm um toolset (agent por padrão para tokens novos, ou graph /
ops / all). Tokens novos veem o working set do agent, não o catálogo
de 80 nomes. Veja Ferramentas MCP.
Um token por agente
Use um token por agente ou persona, para que as escritas fiquem atribuíveis e a revogação não interrompa todo mundo. Nunca cole um token em chat, repositório git ou no próprio ValorBrain.