Authentication (REST)
Operational guidance lives in Platform › Authentication. REST clients authenticate with Bearer secrets that begin with sm_.
Bearer format
Authorization: Bearer sm_org_rw_xxxxxxxxxxxxxxxxxxxxxxxx
Supported prefixes emitted by the dashboard or tooling:
| Prefix | Origin | Typical use |
|---|---|---|
sm_org_rw_ / sm_org_r_ | Settings → API Keys | Integrations spanning multiple volumes in an org |
sm_proj_rw_ / sm_proj_r_ | Settings → API Keys (project scoped) | Single-product automation |
sm_agent_ | Agents → Create Agent or POST /agents | Profiles with optional system prompts + telemetry labels |
sm_live_ | sm login | CLI workstations |
sm_oauth_ | MCP / connector OAuth | Remote MCP + hosted assistants |
Creating keys safely
API Keys UI (recommended baseline)
Open Settings → API Keys, create a descriptive name, pick org-wide vs single project scope, and copy immediately — plaintext is shown exactly once before being hashed (SHA‑256). Dashboard Setup mirrors these values inside MCP JSON + curl snippets.
Agent keys
Use Agents → Create Agent in the web app whenever you want a keyed profile (sm_agent_…). Programmatic provisioning (POST /agents) still expects the same Passport session mechanism as other dashboard APIs; service-to-service setups should rely on sm_org_/sm_proj_ keys instead until documented service accounts exist.
Rotate or revoke
- Dashboard API Keys table → revoke.
- Agents → Rotate key hits
POST /agents/:agent_id/rotate-key.
Never commit plaintext secrets — prefer .env + secret managers in CI/CD.
Volume checks on /agent/*
ensureAgentVolumeAccess enforces UUID volume_id ownership:
| Key shape | Behaviour |
|---|---|
Org-wide (project_id null) | May access any volume in the same org unless plan/policy blocks |
| Project-scoped | Must reference its bound volume_id |
Historical deployments may still use /agent/connect to decorate fine-grained volume lists — see /api-reference/agents/connect.