Authentication & Scopes

Every request to the Shout API must carry a valid API key. Keys are tenant-scoped: they authenticate as your organization, and what they can do is determined entirely by their scopes.

Passing your key

Two headers are accepted — they are equivalent, pick one:

# Authorization: Bearer (recommended)
curl https://publicapi.shout.com/v1/me \
  -H "Authorization: Bearer $SHOUT_API_KEY"

# X-Api-Key
curl https://publicapi.shout.com/v1/me \
  -H "X-Api-Key: $SHOUT_API_KEY"

Keys always start with sk_. Send the full value exactly as issued.

Caution

Your key is a secret with the same power as an admin integration. Never commit it to source control, embed it in a browser or mobile app, or paste it into a URL. Keep it server-side in a secrets manager. If a key is exposed, revoke it immediately.

Scopes

A key is granted one or more scopes when it’s created. Each endpoint requires a specific scope; a key without it gets 403 insufficient_scope (see errors). Grant the least a given integration needs.

Scope	Grants
forms:read	List and read forms; list workspaces.
forms:write	Create forms.
responses:read	List and read form responses.
contacts:read	List and read contacts, organisations and groups.
contacts:write	Create/update/delete contacts; subscribe/unsubscribe.
tickets:read	List inboxes and tickets; read ticket threads.
tickets:write	Reply to tickets and change ticket status.
webhooks:manage	Create, update, delete and test webhooks.

Check what a key actually holds at any time with GET /v1/me, which returns its scopes array and requires no scope itself.

curl https://publicapi.shout.com/v1/me -H "Authorization: Bearer $SHOUT_API_KEY"

{
  "keyId": "3f9a1c22-8b4e-4d17-9c02-11a2b3c4d5e6",
  "keyName": "Reporting sync",
  "tenantId": "0f6060e2-9842-fff3-f184-3a206ef96c98",
  "scopes": ["forms:read", "responses:read"]
}

Read-only keys for AI agents

If a key will be used by an LLM agent (for example over MCP), grant only read scopes — forms:read, responses:read, tickets:read. Form responses and ticket messages are content submitted by strangers on the internet, and a read-only key bounds what a prompt-injection attempt can do. See the MCP page.

Key lifecycle

Manage keys under Account → Developers → API keys (tenant admins only).

• Shown once. The full key value is displayed only at creation. Store it immediately; it can’t be retrieved later — only the name, prefix and scopes remain visible.
• Expiry (optional). You can set an expiry date when creating a key. After it passes, the key stops authenticating (401).
• Revoking a key. Revoke a key from the same screen to disable it immediately. Revocation is permanent; create a new key to replace it.
• Limit. A tenant can have at most 20 active keys at once. Revoke unused keys to free up slots.

A revoked or expired key returns 401 Unauthorized on every call, exactly like an unknown key — so rotating a key is: create the new one, deploy it, then revoke the old one.

Rate limits

Each key is limited to 120 requests per minute (a sliding window). Over the limit you get 429 Too Many Requests with a Retry-After header (seconds). See Pagination & errors.