Host SaaS API

Your product (the host SaaS) talks to SolutionDesk server-to-server with an API key. End-users never hit these routes from the browser with a staff password.

1. Create an API key

Settings → API keys
Create a key, name it (e.g. production-host).
Copy the raw secret once — it is not shown again.

Send it as:

Authorization: Bearer <api-key>

Invalid or missing keys → 401.

2. Upsert companies and end-users

Key by your own ids (externalId) so MagicLinks and tickets stay stable:

Goal	Integration surface (under `/v1/integration/…`)
End-customer company	Companies upsert
Person at that company	End-users upsert (attributes feed restricted visibility)

Staff can also create companies/users in the dashboard; the host path is for automation.

3. Create tickets on behalf of customers

Create tickets with company linkage, visibility, type/priority, and custom fields. Defaults come from workspace ticket config when omitted.

4. Mint a MagicLink into the portal

POST /v1/integration/portal/links
Authorization: Bearer <api-key>
Content-Type: application/json

{ "externalId": "jane-acme" }

Response:

{ "url": "https://<api-host>/v1/auth/portal/enter?token=…" }

Your host redirects the signed-in end-user to that URL (usually once). The link is single-use; reuse shows an expired/invalid portal message.

Typical product UX:

User clicks Support in your app.
Your backend mints a link for their externalId.
Browser opens the portal (often on a custom domain).

See the Customer portal guide for what they see next.

5. White-label domains

Settings → Domains — portal (+ optional API) hostnames so cookies stay same-site and branding stays yours.

MCP vs Host API

	Host API (API key)	MCP (staff OAuth)
Who	Your backend	AI agent as a staff member
Auth	Bearer API key	Browser login / OAuth for MCP client
Use	Sync companies, mint portal links	Work tickets day to day

Configure MCP under Account → MCP.