Authentication

OpenBrain SaaS uses Laravel Sanctum personal access tokens for the REST API and MCP (/mcp).

Token abilities

Ability	REST	MCP tools
memory:ingest	POST /api/memories, PUT /api/memories, POST /api/memories/batch	memory_ingest
memory:search	POST /api/memories/search, GET /api/memories/{id}	memory_search, memory_get
memory:admin	PATCH /api/memories/{id}, DELETE /api/memories/{id}	memory_update, memory_delete
organization:{uuid}	Binds the token to one tenant	Same

The wildcard ability * grants all scopes (intended for local development only).

Organization context

• Prefer embedding the org in the token: organization:{uuid}.
• Optionally send X-Organization-Id — it must match the token’s organization: ability when both are present.

Creating tokens

$user->createToken('agent-ingest', [
    'organization:'.$organizationId,
    'memory:ingest',
    'memory:search',
]);

Issue separate tokens for search-only automation vs ingest-heavy agents vs admin (update/delete) workflows.

Organization roles (OBS-106)

Role	Dashboard (/app)	API keys	Billing
owner	Full tenant access	Create tokens with any abilities	Yes
member	Memories + API keys	Create tokens (ability checkboxes)	No
readonly	View/search UI	Create search-only tokens	No

Owners invite teammates from the Team page; accept via signed /invitations/accept/{token} (email must match).

Audit log (OB-047)

Successful ingest, upsert, update, delete, and batch operations write org-scoped rows to memory_audit_events (actor user/token, action, thought id, metadata such as outcome/dedupe — never raw content). Owners can review events in the dashboard Audit log.

REST requests

Authorization: Bearer {token}
X-Organization-Id: {uuid}   # optional when token includes organization:{uuid}
Content-Type: application/json

MCP

• Production: Bearer token required on every /mcp request.
• Local: Unauthenticated MCP is allowed only when APP_ENV=local and OPENBRAIN_DEFAULT_ORGANIZATION_ID is set.

Rate limits

Per organization + token (requests per minute, configurable via .env):

Variable	Default	Applies to
OPENBRAIN_RATE_LIMIT_INGEST	60	ingest, upsert, batch
OPENBRAIN_RATE_LIMIT_SEARCH	120	search, get
OPENBRAIN_RATE_LIMIT_ADMIN	30	update, delete
OPENBRAIN_RATE_LIMIT_MCP	90	/mcp endpoint

Exceeded limits return HTTP 429 with Retry-After.