Tokens

Gerado da matriz de credenciais · versão 1 · sha 1e1ecfce3a57. Não edite à mão: a fonte é src/credential-matrix.ts no engine.

Para o cliente existe um prefixo, vbm_, e dois hosts: o MCP em https://mcpbrain.valor.digital/mcp e o REST em https://valorbrain-api.valor.digital. O tenant vem sempre da credencial: não envie X-Tenant-ID e não invente um UUID de tenant. Um token por pessoa, em qualquer harness e persona: agentes e harnesses se identificam pelos cabeçalhos do contrato (X-Source-Agent, X-ValorBrain-Harness, X-Run-Kind, X-Requested-By, X-Agent-Team; ou as envs VALORBRAIN_SOURCE_AGENT, VALORBRAIN_RUN_KIND, VALORBRAIN_REQUESTED_BY, VALORBRAIN_AGENT_TEAM), nunca por um token por agente. Gateway e integração existem para sistemas sem pessoa.

Para conectar um cliente passo a passo, veja Conectar.

Credenciais

As credenciais não são intercambiáveis. Cada recusa abaixo é a resposta exata do servidor; o catálogo de erros diz o que fazer em cada uma. Nenhuma credencial de cliente abre as rotas de administração, de crédito e assinatura ou /metrics.

Variáveis de ambiente do cliente

Nomes antigos ainda lidos, com aviso de depreciação: VALORBRAIN_TOKEN, VALORBRAIN_API_TOKEN.

Detalhe por credencial

Token MCP (vbm_)

• Emitida por: Signup agent-native (mcp_token da resposta) — npx -y @valorbrain/cli@latest init --agent --agent-caller <id> --json (POST /api/v1/agents/signup); Reemissão pela chave vb_agent_ (mesmo teto do signup; revoga o anterior) — POST /api/v1/agents/mcp-token (Authorization: Bearer vb_agent_…); App → Configurações → Tokens MCP — https://valorbrain.valor.digital/settings/mcp-tokens (POST /api/v1/mcp/tokens); Device flow do connect (um token por computador) — npx -y @valorbrain/connect (POST /api/v1/cli/device/code no app); OAuth 2.1 (consentimento, código + PKCE) — POST /oauth/token grant_type=authorization_code; EMA: asserção do IdP da empresa — POST /oauth/token grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer.
• Guardada em: mcp_tokens.token_hash (sha256).
• Tenant: mcp_tokens.tenant_id (header nunca troca o tenant).
• Usuário: mcp_tokens.user_id; agente/persona por X-Source-Agent, senão a persona do token (intended_agent_platform que não é nome de harness), senão X-ValorBrain-Harness, senão a plataforma de harness do token, senão clientInfo (só sem plataforma no token), senão o nome do token.
• Escopo: Escopos do token (read, write, admin, granulares de src/mcp-scopes.ts; [] não concede nada), toolsets aditivos (agent,graph), coleções permitidas e audience (RFC 8707). Token OAuth pedido para o MCP ou para o app vale nos dois (audience irmã, ADR-085); o ingest exige write.
• Validade: Sem expiração quando criado no app. Signup: 30 dias até o claim, que remove a expiração. OAuth: até a validade de quem consentiu ou VALORBRAIN_OAUTH_TOKEN_MAX_TTL_DAYS. EMA: token_ttl_seconds do emissor (padrão 900 s). (revogação · rotação)
• Limite: authenticated e search, por sha256 do token (limite)

Chave de conta de agente (vb_agent_)

• Emitida por: Signup agent-native (api_key da resposta) — POST /api/v1/agents/signup.
• Guardada em: shadow_tenants.api_key_hash (sha256).
• Tenant: shadow_tenants.tenant_id, só com tenants.billing_status = 'active'.
• Usuário: shadow_tenants.default_user_id (agent-default).
• Escopo: Escopos implícitos read write mcp read_log:read secrets no guard REST (sem billing, preço, admin nem credenciais de conector); teto read write no consentimento OAuth.
• Validade: 30 dias a partir do signup se ninguém fizer o claim; depois do claim não expira. (revogação · rotação)
• Limite: authenticated e search, por sha256 da chave (limite)

Chave de serviço (vb_)

• Emitida por: Provisionamento do tenant (saas-service) — POST /api/v1/admin/tenants/:id/api-tokens (rota de administração da plataforma); Device flow da CLI/valorcode no app — POST /api/v1/cli/device/token no app.
• Guardada em: api_tokens.token_hash (sha256).
• Tenant: api_tokens.tenant_id, só com tenants.billing_status = 'active'.
• Usuário: api_tokens.user_id.
• Escopo: Escopos implícitos read write mcp read_log:read secrets no guard REST (sem billing, preço, admin nem credenciais de conector); teto read write no consentimento OAuth.
• Validade: api_tokens.expires_at quando definido; sem expiração caso contrário. (revogação · rotação)
• Limite: authenticated e search, por sha256 da chave (limite)

Chave de ingest do workspace (fk_)

• Emitida por: App → Configurações → Chaves de API — https://valorbrain.valor.digital/settings/api-keys.
• Guardada em: SaaS api_keys (hash do segredo).
• Tenant: Workspace dono da chave no SaaS.
• Usuário: Não carrega usuário; a escrita é atribuída ao workspace.
• Escopo: Só ingest.
• Validade: Expiração da chave quando definida; sem expiração caso contrário. (revogação · rotação)
• Limite: saas_ingest, por credencial (limite)

Sessão do painel

• Emitida por: Login no app — https://valorbrain.valor.digital/login.
• Guardada em: cookie HttpOnly no navegador.
• Tenant: Workspace ativo da sessão.
• Usuário: Usuário logado.
• Escopo: Papel do membro no workspace.
• Validade: Validade da sessão do app; não é contrato de integração. (revogação · rotação)
• Limite: Limites do app (limite)