Authentication

UnifiedMemory accepts browser sessions for the product UI and scoped bearer keys for API, MCP, gateway, and agent integrations. For agent/runtime calls, scoped keys are the normal path.

Authorization: Bearer <scoped-key>

Do not place admin keys in agent config, public docs, screenshots, proof artifacts, or committed files.

Key types

Type	Intended use	Notes
Scoped agent key	Claude, Codex, Hermes, OpenClaw, Gemini, Cursor, VS Code, REST clients	Bound to source app, container, capabilities, and default scope.
Connector token	Short-lived setup/bootstrap through Connections	Used to establish a scoped integration without pasting admin credentials.
Admin/owner key	Operator workflows, cleanup, proof, and controlled live verification	Keep out of normal agent runtime.
Browser session	Product UI such as dashboard, review, settings, and Courtroom workspace	Server-owned session/cookie flow; not an MCP/API substitute.

Effective identity

The authenticated key or session decides the effective identity:

Field	Source of truth
workspace_id / container_tag	Key/session metadata and route.
source_app	Key metadata.
agent_id	Key binding when present.
agent_scope	Key metadata, normally own.
capabilities	Key grants.

If a request body or header claims a different agent_id, source_app, or scope, UnifiedMemory should preserve that only as diagnostics/audit and use the key-derived identity for authorization.

Capability failures

Expected status codes:

Status	Meaning
401	Missing, malformed, expired, revoked, or unknown credential.
403	Credential is valid but lacks the requested container, route, capability, or scope.
404	Resource is not found or not visible to the authenticated principal.
422	Credential is accepted, but the request payload is invalid.

Examples:

• A key with recall capability but no write capability receives 403 from retain/writeback.
• A Claude-scoped key asking for Codex working memory should receive no leaked memory; if the route requires direct access, it should receive 403 or scoped empty results.
• A missing bearer token receives 401.

Safe examples

Use environment variables:

export UNIFIED_MEMORY_API_KEY="<scoped-key>"
curl https://edge-api.jithendranara.dev/api/v2/containers/jeethendra/recall \
  -H "Authorization: Bearer $UNIFIED_MEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"What docs changed?","limit":5}'

Use connector tokens only for setup flows:

curl https://edge-api.jithendranara.dev/mcp/connect/<connector-token> \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"client":"codex"}'

Rotation and reissue

If a key is exposed or no longer needed:

• revoke or rotate it from Connections or Settings/Ops;
• reissue a new scoped key for the same integration;
• update the local agent config or environment variable;
• verify the selected key with a real tool call, not just a browser preflight.

General credential rotation should not return raw keys through broad web settings surfaces. Use an explicit key reveal/reissue flow.

Sessions and logout

Browser sessions are for the hosted UI. Logging out should revoke the backend session and clear relevant cookies before redirecting to login. A changed password should require a fresh session and should not silently restore an old browser session.

Next steps

• Connect a scoped integration with Connect an Agent.
• Review capability expectations in Rate limits and auth limits.
• Inspect API failures in Errors.