For the complete documentation index, see llms.txt. This page is also available as Markdown.

Authentication

Brain authenticates three caller types: humans, internal agents, and external agents. The same API endpoints serve all three. Only the credential differs.

Caller
Mode
Credential

Human

Self-serve email + password, or a linked wallet

Bearer owner JWT

Internal agent

Brain-issued service token (your own backend)

Bearer service token

API partner

Tenant API key

Bearer brain_sk_… key

External agent

SIWX (EIP-4361 over Base) + on-chain scope

access_token from the SIWX exchange

Every credential is presented the same way: Authorization: Bearer <token>. There is one bearer mechanism, not several. The brain_sk_test_… / brain_sk_live_… value you copy from the Console is a tenant API key. The SDK takes it as new Brain({ apiKey }). See Server API key below.

Self-serve signup is gated by the BRAIN_SELF_SERVE_SIGNUP flag and is sandbox-only (RFC 0002): a new tenant can read and propose, but moves no money until the existing promotion + external-audit gates clear. Hosted SSO (Auth0/SAML) is planned (roadmap), not in the MVP.

Server API key (brain_sk_)

The credential a server-side integration uses is a Brain-issued tenant API key with a brain_sk_ prefix. It authenticates directly as a bearer credential; there is no token exchange step.

Property
Value

Format

brain_sk_test_… (sandbox) / brain_sk_live_… (live)

Issued by

The Console, per tenant

Presented as

Authorization: Bearer brain_sk_…, or new Brain({ apiKey: "brain_sk_…" }) in the SDK

Scopes

ledger:read, audit:read

Sandbox vs live

Distinct keys per environment

Lifetime

Until revoked or rotated by a tenant admin

Rate limits, idempotency, and audit attribution are all keyed off this token.

Human Authentication (self-serve email + password)

A developer self-provisions a sandbox tenant, verifies their email, then logs in for a short-lived owner JWT carrying management/read/approve scopes only. Never payment_intent:propose / payment_intent:execute / execution:propose (money movement is an agent + Β§6-gate concern, never a human-login capability).

1. Sign up. Provisions a sandbox tenant + owner.

In production, the API emails the token through the configured ESP client (EMAIL_ENDPOINT, EMAIL_API_KEY, optional EMAIL_FROM). If BRAIN_SELF_SERVE_SIGNUP is enabled in production without ESP credentials, API boot fails before signup routes are served.

2. Verify the email. Single-use, short-TTL token, scoped to the tenant.

3. Log in. Email + password -> owner JWT.

An unknown email and a wrong password return the same 401 auth_invalid_credentials (no user enumeration); an unverified account returns 403 auth_email_unverified.

Wallet Authentication (SIWX). Agents and humans

External agents. And humans who link a wallet. Authenticate with Sign-In With X (EIP-4361 over Base). An owner can link a wallet to their tenant:

At sign-in, SIWX resolves the wallet: one linked to a human mints an owner JWT (the same management scopes as email login); an agent wallet (registered + active in BrainMCPAgentRegistry) mints an agent token.

Step 1: Construct the SIWX Message

A nonce is obtained from POST /v1/auth/siwx/challenge (Redis-held, 5-minute TTL).

Step 2: Sign with the Identity Key

The agent (or human's linked wallet) signs the message with the key registered in BrainMCPAgentRegistry / linked via wallet_identities.

Step 3: Exchange for a Token

Step 4: Use the Token

The MCP auth chain additionally verifies the agent record is active and that the JWT's scope_hash matches the on-chain hash in BrainMCPAgentRegistry. Agents can read, contribute evidence, and propose. Never execute (there is no execute tool; every settlement passes the Β§6 gate).

ScopeAttestation EIP-712 Type

Token Lifetimes

Token
Default TTL
Refreshable

Owner JWT (email/wallet)

15 minutes

Yes. Log in / re-sign again

Agent token (SIWX)

1 hour

Yes, by re-signing SIWX

Server API key (brain_sk_, Console)

90 days

Rotated by tenant admin

Service-token mint (/v1/auth/service-token)

1 hour

Re-mint (break-glass sandbox/testnet)

Email-verification token

24 hours

No, single-use

Policy verdict

60 seconds

No, single-use

Owner JWTs include surfaces:admin so a tenant admin can connect or revoke Slack, Teams, and email approval surfaces. Surface onboarding endpoints derive the Brain tenant from this bearer principal, not from request bodies.

Revocation

Type
How to Revoke

Agent scope

DELETE /v1/agents/{id}/scopes/{capability}

Agent registration

POST /v1/agents/{id}/deactivate (also called on-chain)

Token

Short-lived by design; tokens expire (15 min / 1 hour)

What's Next

🌐 API Overview

Endpoints, versioning, rate limits.

πŸ“œ BrainMCPAgentRegistry

The on-chain agent registry.

Last updated