Tokens

Generated from the credential matrix · version 1 · sha 1e1ecfce3a57. Do not edit by hand: the source is src/credential-matrix.ts in the engine.

A client needs one prefix, vbm_, and two hosts: MCP at https://mcpbrain.valor.digital/mcp and REST at https://valorbrain-api.valor.digital. The tenant always comes from the credential: do not send X-Tenant-ID and do not invent a tenant UUID. One token per person, any harness and persona: agents and harnesses identify themselves through the contract headers (X-Source-Agent, X-ValorBrain-Harness, X-Run-Kind, X-Requested-By, X-Agent-Team; or the env VALORBRAIN_SOURCE_AGENT, VALORBRAIN_RUN_KIND, VALORBRAIN_REQUESTED_BY, VALORBRAIN_AGENT_TEAM), never through a token per agent. Gateway and integration credentials exist for systems without a person.

To connect a client step by step, see Connect.

Credentials

The credentials are not interchangeable. Each refusal below is the server's exact answer; the error catalog says what to do about each one. No client credential opens the admin, credit and subscription routes or /metrics.

Client environment variables

Older names still read, with a deprecation warning: VALORBRAIN_TOKEN, VALORBRAIN_API_TOKEN.

Per-credential detail

MCP token (vbm_)

• Issued by: Agent-native signup (mcp_token in the response) — npx -y @valorbrain/cli@latest init --agent --agent-caller <id> --json (POST /api/v1/agents/signup); Reissue with the vb_agent_ key (same ceiling as the signup; revokes the previous one) — POST /api/v1/agents/mcp-token (Authorization: Bearer vb_agent_…); App → Settings → MCP Tokens — https://valorbrain.valor.digital/settings/mcp-tokens (POST /api/v1/mcp/tokens); Connect device flow (one token per computer) — npx -y @valorbrain/connect (POST /api/v1/cli/device/code no app); OAuth 2.1 (consent, code + PKCE) — POST /oauth/token grant_type=authorization_code; EMA: company IdP assertion — POST /oauth/token grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer.
• Stored in: mcp_tokens.token_hash (sha256).
• Tenant: mcp_tokens.tenant_id (a header never switches the tenant).
• User: mcp_tokens.user_id; agent/persona from X-Source-Agent, else the token's persona (an intended_agent_platform that is not a harness name), else X-ValorBrain-Harness, else the token's harness platform, else clientInfo (only when the token has no platform), else the token name.
• Scope: Token scopes (read, write, admin, granular ones from src/mcp-scopes.ts; [] grants nothing), additive toolsets (agent,graph), allowed collections and audience (RFC 8707). An OAuth token asked for MCP or for the app is valid at both (sibling audience, ADR-085); ingest requires write.
• Validity: No expiry when created in the app. Signup: 30 days until the claim, which removes the expiry. OAuth: up to the consenter's validity or VALORBRAIN_OAUTH_TOKEN_MAX_TTL_DAYS. EMA: the issuer's token_ttl_seconds (default 900 s). (revocation · rotation)
• Rate limit: authenticated and search, per sha256 of the token (rate limit)

Agent account key (vb_agent_)

• Issued by: Agent-native signup (api_key in the response) — POST /api/v1/agents/signup.
• Stored in: shadow_tenants.api_key_hash (sha256).
• Tenant: shadow_tenants.tenant_id, only while tenants.billing_status = 'active'.
• User: shadow_tenants.default_user_id (agent-default).
• Scope: Implicit scopes read write mcp read_log:read secrets at the REST guard (no billing, pricing, admin or connector credentials); capped at read write on the OAuth consent.
• Validity: 30 days from signup unless someone claims the workspace; after the claim it does not expire. (revocation · rotation)
• Rate limit: authenticated and search, per sha256 of the key (rate limit)

Service key (vb_)

• Issued by: Tenant provisioning (saas-service) — POST /api/v1/admin/tenants/:id/api-tokens (rota de administração da plataforma); CLI/valorcode device flow in the app — POST /api/v1/cli/device/token no app.
• Stored in: api_tokens.token_hash (sha256).
• Tenant: api_tokens.tenant_id, only while tenants.billing_status = 'active'.
• User: api_tokens.user_id.
• Scope: Implicit scopes read write mcp read_log:read secrets at the REST guard (no billing, pricing, admin or connector credentials); capped at read write on the OAuth consent.
• Validity: api_tokens.expires_at when set; no expiry otherwise. (revocation · rotation)
• Rate limit: authenticated and search, per sha256 of the key (rate limit)

Workspace ingest key (fk_)

• Issued by: App → Settings → API keys — https://valorbrain.valor.digital/settings/api-keys.
• Stored in: SaaS api_keys (hash do segredo).
• Tenant: The workspace that owns the key in the SaaS.
• User: Carries no user; writes are attributed to the workspace.
• Scope: Ingest only.
• Validity: The key's expiry when set; no expiry otherwise. (revocation · rotation)
• Rate limit: saas_ingest, per credential (rate limit)

Dashboard session

• Issued by: App login — https://valorbrain.valor.digital/login.
• Stored in: cookie HttpOnly no navegador.
• Tenant: The session's active workspace.
• User: The signed-in user.
• Scope: The member's role in the workspace.
• Validity: The app session's validity; not an integration contract. (revocation · rotation)
• Rate limit: App limits (rate limit)