Managing Tokens & the REST API

Everything the MCP server does, it does by relaying a scoped agent key to the Sapot Chat REST API. That means two things you can do without ever touching MCP: mint and revoke keys over HTTP, and call the same scoped endpoints directly with curl or any HTTP client. The exact same default-deny allowlist and safety boundaries apply either way.

The admin token API

Agent keys are managed under a standard account-scoped REST resource. All four actions are admin-only and must be called with a full-access personal access token (or a dashboard session) — a scoped agent key cannot manage keys, because the token-management endpoints are deliberately kept off the agent allowlist.

Provision and revoke keys with an admin’s personal access token, not with a scoped agent key. Handing an agent the ability to mint its own keys would defeat the scope model.

Method	Path	Action
`GET`	`/api/v1/accounts/{account_id}/agent_access_tokens`	List keys (masked)
`POST`	`/api/v1/accounts/{account_id}/agent_access_tokens`	Create a key — plaintext token returned once
`GET`	`/api/v1/accounts/{account_id}/agent_access_tokens/{id}`	Show one key (masked)
`DELETE`	`/api/v1/accounts/{account_id}/agent_access_tokens/{id}`	Revoke a key — it stops authenticating immediately

Create a key

curl -X POST https://<your-api-host>/api/v1/accounts/YOUR_ACCOUNT_ID/agent_access_tokens \
  -H "api_access_token: YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "agent_access_token": {
          "name": "triage-bot",
          "scopes": ["conversations:read", "conversations:write"],
          "expires_at": "2026-12-31T00:00:00Z"
        }
      }'

The request body accepts name (required), scopes (array, at least one; unknown values are rejected), and an optional expires_at. Valid scope values are the capability grammar: conversations:read, conversations:write, contacts:manage, knowledge:manage, flows:manage, flows:publish, campaigns:draft, templates:manage, automation:manage, reports:read, plus * for full access. See the Authentication & Scopes page for what each grants. The create response is the only place the plaintext token is ever returned:

{
  "id": 42,
  "name": "triage-bot",
  "token": "hE4fLv…full-secret-shown-once…QwGJw",
  "token_preview": "hE4fLv…QwGJw",
  "scopes": ["conversations:read", "conversations:write"],
  "expires_at": "2026-12-31T00:00:00Z",
  "revoked_at": null,
  "last_used_at": null,
  "usage_count": 0,
  "active": true,
  "created_at": "2026-07-06T10:00:00Z",
  "created_by": { "name": "Ada Admin", "email": "[email protected]" }
}

Copy token now. Every subsequent list/show returns only token_preview (first 6 + last 4 characters) — the full secret is never retrievable again. usage_count is the metered call count for that key; last_used_at reflects its most recent successful call.

Direct REST without MCP

The same scoped key works against the documented Sapot Chat REST endpoints — no MCP server in the path. Two differences from the MCP transport:

Send the key in the api_access_token header (not Authorization: Bearer — that form is the MCP transport’s, which the server renames on relay).
The account id lives in the URL path, not the X-Sapot-Account-Id header.

curl "https://<your-api-host>/api/v1/accounts/YOUR_ACCOUNT_ID/conversations?status=open" \
  -H "api_access_token: YOUR_AGENT_KEY"

MCP vs. direct REST

	MCP	Direct REST
Auth header	`Authorization: Bearer YOUR_AGENT_KEY`	`api_access_token: YOUR_AGENT_KEY`
Account id	`X-Sapot-Account-Id` header	in the URL path
Endpoint	`https://mcp.sapot.ai/mcp`	your API base URL
Interface	46 named intent-level tools	documented REST endpoints

For reference, the MCP connect command is:

claude mcp add --transport http sapot https://mcp.sapot.ai/mcp --header "Authorization: Bearer YOUR_AGENT_KEY" --header "X-Sapot-Account-Id: YOUR_ACCOUNT_ID"

Same boundaries, either path

A scoped key is governed identically over REST and over MCP — the enforcement lives in the Rails API, not the MCP layer:

Default-deny allowlist

A key reaches only the endpoints its scopes map to; a missing scope returns 401 naming the required scope. The key is bound to the one account it was minted in — a path account id that doesn’t match is refused.

Flow graph stripped

Flow-agent reads serve an agent-safe view with the Designer graph removed, and publish failures return an opaque error to agent keys. No create/export/import.

Campaigns forced to draft

Agent-authored campaigns are pinned to a non-sending draft server-side, so a key can prepare a blast but never send it. A human sends from the dashboard.

Metered per plan

Only allowed, successful (2xx) calls consume quota — a denied, rejected, or errored request counts nothing. Over the plan’s per-period allowance, requests return 429.

Because the API is the single enforcement point, testing a scope over curl is a faithful preview of how the same key behaves through an MCP tool.

Getting Started

Tool Reference

Reference

The admin token API

Create a key

Direct REST without MCP

MCP vs. direct REST

Same boundaries, either path

Default-deny allowlist

Flow graph stripped

Campaigns forced to draft

Metered per plan

Reference

REST API reference

Authentication & Scopes

​The admin token API

​Create a key

​Direct REST without MCP

​MCP vs. direct REST

​Same boundaries, either path

Default-deny allowlist

Flow graph stripped

Campaigns forced to draft

Metered per plan

​Reference

REST API reference

Authentication & Scopes

The admin token API

Create a key

Direct REST without MCP

MCP vs. direct REST

Same boundaries, either path

Reference