Integration guide
Connect once, keep the contract small.
This is the page to hand to an integration partner. It covers the full loop: authenticate, configure a callback, verify delivery, and resolve human approvals.
What you need
1
client_id + PKCE
Used to run the authorization-code flow with login + consent.
2
workspace_id
Used to store webhook settings and fetch inbox-specific tickets or approvals.
3
callback_url + signing_secret
Used for outbound webhook delivery and signature verification.
Step 1. Register the callback
Store the partner callback URL and signing secret for the workspace before sending any events.
PUT https://api.supportforagents.app/v1/workspaces/{workspace_id}/webhook-settings
callback_url = https://example.com/webhooks/supportforagents
signing_secret = *** Step 2. Authorize with PKCE
Send the user through the login + consent screen first.
GET https://auth.supportforagents.app/oauth/authorize
response_type=code
code_challenge_method=S256
redirect_uri=https://profitroost.com Step 3. Exchange the code
Post the authorization code plus code_verifier to mint access and refresh tokens.
POST https://auth.supportforagents.app/oauth/token
grant_type=authorization_code
code=...
code_verifier=...
redirect_uri=https://profitroost.com Token response shape: access_token, refresh_token, expires_in, scope, workspace_id.
Step 4. Verify signed webhook delivery
SupportForAgents signs the raw JSON body with HMAC-SHA256 using X-SFA-Timestamp and
X-SFA-Signature.
X-SFA-Timestamp: <unix-seconds>
X-SFA-Signature: HMAC_SHA256(timestamp + "." + rawBody, signing_secret)
X-SFA-Workspace-Id: {workspace_id} {"event":"support.email.received","id":"<uuid>","occurred_at":"<iso8601>","source":"workspace1","data":{"ticket_id":"...","from_email":"...","subject":"...","body":"..."}} The body shape is always top-level event, id, occurred_at, source, and data.
Step 5. Read the inbox and approval queue
Inbox
See the tickets
GET /v1/inboxes/{inbox_id}/tickets
Approvals
See pending human actions
GET /v1/inboxes/{inbox_id}/pending-approvals
Action
Approve or reject
POST /v1/approvals/{approval_id}/approve
POST /v1/approvals/{approval_id}/reject
Step 6. Resolve approvals from MCP
For agent-driven workflows, call the MCP tool when the reply needs a human-safe decision.
POST https://api.supportforagents.app/mcp
tools/call → resolve_approval
decision: approved | rejected Common webhook events
Inbound
support.email.received creates or updates the inbox thread.
support.reply.drafted creates a pending approval.
support.reply.sent marks the approval as sent.