Connect an agent

SAM's entire agent surface is plain HTTP/JSON + Authorization: Bearer <key>. There is no SAM SDK — any runtime that can send an HTTP request works (OpenAI, Cursor/MCP, custom). Agents authenticate by API key / Bearer token / MCP, not a login form.

Get a key from your SAM owner's console (Customer → API keys), then call any leg with Authorization: Bearer <key>. The key is scoped per-tenant + per-permission server-side — a smuggled tenant_id in a body is ignored.

Base URL & leg prefixes

One composed service; each leg is a path prefix. GET /healthz → liveness + honest leg accounting.

Leg	Prefix	Does
SAMShield	/shield	Scan untrusted content for prompt-injection / policy risk
SAMScope	/scope	Issue short-lived scoped credentials
SAMHandler	/handler	Provision agent identities (+ seat payment)
SAMcypher	/cypher	Governed payments / transfers / subscriptions
sam-license	/license	Validate a SAMSerum/Shredder license (gate-on-use)

Envelopes

Every response is one of two shapes. Always check the body status, not just the HTTP code — an escalated payment returns 202 with data.status == "escalated" and is not executed.

Success: {"ok": true,  "data": {…}, "request_id": "req_…", "timestamp": "…"}
Error:   {"ok": false, "error": {"code": "…", "message": "…", "request_id": "req_…"}}

Minimal example (raw HTTP, any language)

POST /cypher/v1/intents
Authorization: Bearer sk_live_…
Content-Type: application/json

{"account_id":"acct","venue":"STRIPE_ISSUING","action_type":"PAY_API",
 "asset":"USD","amount":5,"reason":"api fee","requested_by":"EXECUTOR",
 "idempotency_key":"<uuid you reuse on retry>"}

Idempotency (the money contract)

For any charge, you supply idempotency_key and reuse it on retry so the charge dedupes — there is no safe server-side default. Same (tenant, key) → same receipt; the same key from a different tenant never collides.

Snippets & the full contract

Four reference snippets — all reduce to POST <leg> + Bearer + JSON:

File	Runtime
reference_client.py	stdlib urllib only — the no-SDK proof
raw_http_curl.sh	curl — any shell-capable agent
openai_tool_calling.py	OpenAI function/tool-calling (schema + dispatch)
mcp_tool.py	MCP server (Cursor / Claude Desktop) — the MCP→HTTP bridge

Full field semantics, enums, mandate matching, and the per-leg endpoint catalog live in the Agent Integration Contract (v1) shipped with the suite (examples/agents/AGENT_INTEGRATION_CONTRACT.md).

Reading this with an agent? The whole surface is fetchable as plain text — no scraping this page: /llms.txt (discovery index) · /llms-full.txt (this contract, markdown) · /agent-examples/<file> (the runnable snippets).

Not an agent? Customer login · Operator login