Authentication

API keys

Create a key under Settings → API keys. Give it a name and pick a tier; the tier fixes what the key may do for its whole life. The full secret is shown once, at creation. Revoke a key from the same pane; revocation is immediate. A workspace can hold 10 active keys; one key per tool is the habit that keeps a revoke from breaking anything else.

Keys start with sa_live_ (older keys starting with sk_live_ still work). Send one as a bearer token on every request. The old ?api_key= query parameter is no longer accepted and returns an error that says so.

curl https://app.streamagent.io/api/mcp \
  -H "Authorization: Bearer sa_live_…" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

curl https://app.streamagent.io/api/v1/workspace \
  -H "Authorization: Bearer sa_live_…"

Using a credential on the REST API

Every route under https://app.streamagent.io/api/v1 takes the same bearer header and checks the same scope as the MCP tool of the same name; a key that can list leads over MCP can GET /leads, and a key that cannot, cannot. Errors come back as { "error": { "code", "message" } } with the HTTP status the code implies, lists page with limit and cursor, and writes accept an Idempotency-Key. The full conventions and the route table are on the REST API page.

Key tiers and what they expand to

A tier is a fixed set of scopes. The authorizer checks the scope a tool requires against this set on every call.

Scopes

Assistants connected through sign-in request scopes individually and the workspace owner approves the exact set on a consent screen. Keys get their scopes from the tier above.

Assistant connections

Claude, ChatGPT and Perplexity connect by sign-in rather than by key: the owner approves a consent screen and the assistant receives a token prefixed sat_. The steps per assistant are on the MCP server page. Connected assistants, what each may do, and a revoke action live under Settings → Connected apps.

Rate limits

Every credential gets 600 calls per minute and 10,000 per hour by default. A workspace or a single key can carry its own ceiling; the effective limit is the key's, else the workspace's, else the default.

When you exceed it the response is 429 with a Retry-After header in seconds. Traffic without a valid credential is limited separately by client address, so a burst of failed sign-ins never counts against your key.

Lead privacy

Lead contact details are masked before they leave the workspace unless the owner turns masking off: names, emails, phone numbers and addresses come back with the first character and asterisks. The masking is applied identically to every lead tool.

Errors

The MCP server speaks JSON-RPC and the REST API speaks plain JSON, but authentication failures look the same on both: the HTTP status below, and a WWW-Authenticate header your client can read. On REST the body is { "error": { "code": "unauthorized" } } or "forbidden"; on MCP it is the JSON-RPC error shown.

• Retry 429 after the header value, not before.
• Treat 401 as terminal for that credential: rotate the key or reconnect the assistant.