How to integrate

Connect your platform in four steps.

The short version for partner teams. If they want the fuller contract, send them to /docs/integration.

For agents, start with /.well-known/supportforagents.json and let the manifest drive the rest.

Register the callback URL

Save the partner callback URL and signing secret for the workspace first.

 PUT https://api.supportforagents.app/v1/workspaces/{workspace_id}/webhook-settings 

Get OAuth credentials

Use the client credentials grant to mint a scoped token for the support workflow.

 POST https://auth.supportforagents.app/oauth/token
grant_type=client_credentials
scope=resolve_approval:write 

Receive signed webhooks

Deliver events to your callback URL and verify the HMAC before processing anything.

Headers: X-SFA-Signature, X-SFA-Timestamp, X-SFA-Workspace-Id.

HMAC_SHA256(timestamp + "." + rawBody, signing_secret)

 {"event":"support.email.received","id":"<uuid>","occurred_at":"<iso8601>","source":"workspace1","data":{"ticket_id":"...","from_email":"...","subject":"...","body":"..."}} 

Integration summary

What the partner platform needs to see

Workspace webhook settings
OAuth client credentials grant
Signed webhook delivery
One MCP approval tool: resolve_approval
Production domain: supportforagents.app

If they need the docs surface instead, point them to /docs/integration.