Tough Customer workspace API

Authentication

A workspace admin mints an API key under Integrations → REST API. The key is shown exactly once (only its hash is stored). Send it on every request as a bearer token:

Authorization: Bearer tc_…

A key acts as the admin who minted it — including their Salesforce connection — and reaches exactly the tools that admin sees. If that admin is demoted to member, the key keeps working for member tools only; if they leave the workspace, the key is revoked automatically. Keys belong to one workspace: the {orgId} in the URL must be that workspace's id (the same id as the workspace's MCP URL, shown next to the endpoint on the keys page). Never put a key in a URL — it is refused there, and URLs get logged along the way. Rotate by minting a new key and revoking the old one.

Endpoints

Two routes, both under your workspace's endpoint:

GET  https://app.toughcustomer.ai/api/v1/{orgId}/tools            # the catalog this key may call
POST https://app.toughcustomer.ai/api/v1/{orgId}/tools/{tool}     # run one tool; the JSON body is its arguments

List your scenarios:

curl -s -X POST https://app.toughcustomer.ai/api/v1/{orgId}/tools/list_scenarios \
  -H "Authorization: Bearer tc_…" \
  -H "Content-Type: application/json" \
  -d '{}'

A successful call returns the tool's output decoded as JSON:

{ "ok": true, "tool": "list_scenarios", "result": [ { "id": 42, "name": "Pricing objection", "category": "Roleplay" } ] }

Arguments are validated against the tool's schema before it runs — the same JSON schema MCP clients see in tools/list, and the same schema the catalog returns as inputSchema. Tools without required arguments accept an empty body. Bodies are limited to 2 MiB and must be application/json. Every response is Cache-Control: no-store and carries an X-Request-Id to quote to support.

Errors

Every error is one JSON envelope:

{ "ok": false, "error": "<code>", "message": "…" }

A 401 carries WWW-Authenticate: Bearer. A 404 is deliberately the same body whether the workspace id, the key's workspace or the tool name is wrong.

Rate limits

Each key may make 60 calls per minute (catalog reads and tool calls alike), counted in a fixed calendar-minute window. Every authenticated response carries X-RateLimit-Limit and X-RateLimit-Remaining; over the limit you get 429 rate_limited with Retry-After (seconds) and retryAfterSeconds in the body. Calls resume in the next minute. Need more? Ask support@toughcustomer.ai.

Tools

Every key reaches the member tools; behavior labels come from the same certification the server publishes to MCP clients as tool annotations. Salesforce-backed tools run on the key owner's Salesforce connection.

Admin tools

Available while the key's owner is a workspace admin — analytics export, scenario and rubric authoring, and member invitations. With a demoted owner these answer 403.

Workspace custom tools

Custom tools authored under Integrations → Custom tools (Salesforce GraphQL, HTTP APIs, Claude agents) are per-workspace, so they are not in the OpenAPI document: read them from your workspace's catalog (GET …/tools, entries with kind: "workspace") and call them by name exactly like a built-in tool.

OpenAPI

The machine-readable specification is generated from the same tool definitions as this page and the MCP server, so it cannot drift from the live API:

https://app.toughcustomer.ai/api/v1/openapi.json

OpenAPI 3.1, bearer security scheme, one operation per built-in tool with its request schema, and the error envelope above. Import it into Postman, Bruno, Swagger UI or your code generator; the document is public and CORS-open. An in-page API explorer is coming with the user-registration endpoint.

Data handling

Calls read and write only the key's workspace, attributed to the key's owner and to the key itself in the workspace's usage ledger. Unexpected errors return a reference id instead of internal details. See the Privacy Policy for what we store and how AI providers process session content, and the Terms of Service for acceptable use. Prefer an OAuth sign-in for a person's own use? That is the MCP connector.