For partners

Operator mode and X-Tenant-Id

Use one partner key for everything, and name the client org on each content call with a header.

One key, one header

A partner account in operator mode needs only its partner key. Every request sends Authorization: Bearer <partner key>. Which endpoint you call decides the rest:

Endpoints	Send	Does
`/v1/partner/**`	the key alone	Create and manage your client orgs, plans, redirect URIs, usage and your partner webhook.
everything else under `/v1/**`	the key and `X-Tenant-Id: <org external_ref>`	Acts as that org: connect its social accounts, upload media, publish, handle comments and direct messages.

Operator mode is switched on by WaSparks for your partner account. If a content call with your partner key returns 403 partner_key_not_allowed, it is not on yet: write to us.

What X-Tenant-Id is

X-Tenant-Id is the external_ref you set when you create an org: your own id for that client. You never have to store an id of ours. If you did not set an external_ref, set one with PATCH /v1/partner/orgs/{orgId}.

POST /v1/partner/orgs
{ "name": "Acme Coffee", "external_ref": "acme-001", "plan_code": "growth" }

GET /v1/org
Authorization: Bearer <partner key>
X-Tenant-Id: acme-001

The rules:

Missing or blank on a content endpoint: 400 tenant_required.
A ref that is not one of your orgs, either unknown or someone else's: 404 not_found. The two cases cannot be told apart, on purpose.
The key still needs the permission for the route, or you get 403 insufficient_permission.
The header is ignored on /v1/partner/**.
Rate limits, idempotency keys and usage are scoped to the org in the header, so one client cannot affect another. A call counts against both the partner key's limit and the org's.

First calls, in order

All with the partner key. The first four need no header.

List plans GET /v1/partner/plans shows the plans you can put orgs on. POST /v1/partner/plans creates your own.
Create a client org POST /v1/partner/orgs. Set external_ref to your id for that client. Repeat for every client.
Register a redirect URI POST /v1/partner/redirect-uris with the HTTPS URL users return to after the consent screen. It applies to all your orgs.
Register one webhook POST /v1/partner/webhook-subscriptions, for all your clients (see below).

From here on, add X-Tenant-Id: <that client's external_ref>:

Check you are in GET /v1/org returns the org the header names.
Connect accounts POST /v1/connect/sessions, send the user to url, then read the session and connect their accounts. See Connect social accounts.
Publish and listen Publish posts, then handle comments and messages.

The Postman collection follows the same order. Download it from the API reference, put your key in partner_key, and run the Quickstart folder.

One webhook for all clients

A single partner subscription can carry both kinds of event:

Content events for any of your orgs: new comments and messages, post results, accounts that need reconnecting.
Provisioning and usage events: org created or suspended, usage.daily_ready.

Every delivery has org_id and, for content events, workspace_id. Route on org_id: the org record has your external_ref. Webhooks covers signatures and retries.

Keep the partner key safe

The partner key can act on every one of your clients. Keep it on your server, never in a browser or mobile app. If it leaks, tell us right away so we can rotate it.

Your clients should know that, in operator mode, your software can read and act on their content. That is the point of the mode, and your own terms with them should say so.

Per-org keys instead

If you want a credential that is limited to one client, create an org key with POST /v1/partner/orgs/{orgId}/api-keys. With an org key you drop X-Tenant-Id, and the key can only reach that org. You can use both approaches side by side. See Provisioning clients.

Next: Provisioning clients