---
agent_auth: bearer
auth_type: oauth2
token_format: vbm_
token_issuer: workspace (human-created MCP token) or OAuth authorization server
header: Authorization
mcp_endpoint: https://mcpbrain.valor.digital/mcp
oauth_discovery: https://valorbrain.valor.digital/.well-known/oauth-authorization-server
protected_resource: https://valorbrain.valor.digital/.well-known/oauth-protected-resource
---

> Nota: este dominio e o site publico do ValorBrain. O servico descrito aqui (MCP, OAuth, API) roda em https://valorbrain.valor.digital - os endpoints abaixo apontam para ele.


# auth.md — ValorBrain authentication for agents

One OAuth access token covers MCP and SaaS ingest. The other credentials below
exist for narrower cases; do not substitute one for another.

## MCP and memory tools

- MCP endpoint: https://mcpbrain.valor.digital/mcp
- Supported engine REST endpoint: https://valorbrain-api.valor.digital
- OAuth discovery: https://valorbrain.valor.digital/.well-known/oauth-authorization-server
- Protected resource metadata: https://valorbrain.valor.digital/.well-known/oauth-protected-resource
- Direct token format: `vbm_…`
- Header: `Authorization: Bearer <token>`

Prefer OAuth when the client supports it. A human can create a dedicated MCP token
at https://valorbrain.valor.digital/settings/mcp-tokens. The same scoped `vbm_…` token works on
MCP, supported memory REST routes and SaaS ingest. It carries tenant, user and
agent scope. Call `whoami` after connecting and stop if the workspace or user is
wrong.

## Public SaaS ingest

- Endpoint: `POST https://valorbrain.valor.digital/api/v1/ingest`
- Credential: your `vbm_…` OAuth access token, or a workspace API key `fk_….sk_…`
- Header: `Authorization: Bearer <token>`
- Scope: an OAuth token needs `write`. Without it the answer is 403 with
  `error="insufficient_scope"`.
- Contract: https://valorbrain.valor.digital/openapi.json

The workspace it writes to comes from the credential, never from a header. On 401
and 403 the response carries `WWW-Authenticate: Bearer …,
resource_metadata="https://valorbrain.valor.digital/.well-known/oauth-protected-resource"`, which
is where an unauthenticated client starts.

A workspace API key works only on the SaaS ingest endpoint. It is not an MCP token
and does not authenticate dashboard knowledge routes.

## Device authorization for engine REST

A headless client can request a device code from
`POST https://valorbrain.valor.digital/api/v1/cli/device/code`. A human approves the displayed
code at the returned verification URL. The client polls
`POST https://valorbrain.valor.digital/api/v1/cli/device/token` and receives a `vb_…` engine
REST token once.

## Dashboard session

Dashboard APIs use the signed web session cookie. They are not a stable public
integration contract. Use MCP, engine REST or SaaS ingest for agents and external
systems.

Never put tokens in prompts, source control, logs or shared memory. Use one token
per agent or persona so it can be revoked without interrupting the others.