Getting started

Authentication

Send your key as a bearer token, know what the key is allowed to do, and read the 401 and 403 codes.

Send the key

Every request carries the key in the Authorization header:

Authorization: Bearer wsk_live_org_3fa9c1d2e4b5a6c7d8_8d2e5f0a1b3c4d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6

A key looks like wsk_<env>_<scope>_<prefix>_<secret>:

env is live or test. Use live keys; test is reserved for a sandbox that is not available yet.
scope is partner or org.
prefix is public. It is what the API shows back as key_prefix, so you can tell keys apart.
secret is the secret part. We store only a hash of the key and cannot show it again.

Keep keys on your server. Never put one in a browser or mobile app. If a key leaks, tell us at hello@wasparks.com and we rotate it; for org keys you can also revoke one yourself with DELETE /v1/partner/orgs/{orgId}/api-keys/{keyId}.

Where keys come from

Partner keys are issued by WaSparks when your partner account is set up. Write to us.
Org keys are created by the partner with POST /v1/partner/orgs/{orgId}/api-keys, which returns the plaintext key once. For a business that integrates directly, we create its first key. See Provisioning clients.

Two surfaces

Surface	Path	Accepts
Partner API	`/v1/partner/**`	Partner keys.
Content API	everything else under `/v1/**`	Org keys, and partner keys in operator mode with an `X-Tenant-Id` header.

A key on the wrong surface is refused: 403 partner_key_not_allowed for a partner key on the Content API, 403 org_key_not_allowed for an org key on the Partner API.

X-Tenant-Id

In operator mode a partner key acts as one org per request. Send the org's external_ref, the id you chose for that client when you created the org:

Authorization: Bearer wsk_live_partner_…
X-Tenant-Id: acme-001

Missing or blank on a Content API call: 400 tenant_required.
A ref that is not one of your orgs, or belongs to someone else: 404 not_found. The two cases look the same on purpose.
The header is ignored on /v1/partner/** and when you use an org key.

The full picture is in Operator mode and X-Tenant-Id.

Permissions

A key also needs the permission an operation asks for. The API reference shows it in brackets, such as [posts:write]. A key without it gets 403 insufficient_permission. A few operations, such as GET /v1/org and GET /v1/workspaces, need only a valid key.

Partner key permissions: orgs:read, orgs:write, org_keys:write, plans:read, plans:write, usage:read, branding:write, domains:write, partner_webhooks:write. A partner in operator mode can also hold any org permission.

Org key permissions: accounts:read, accounts:write, media:write, posts:read, posts:write, comments:read, comments:write, messages:read, messages:write, webhooks:write, usage:read, workspaces:write.

When you mint an org key, give it only what that integration needs.

Authentication errors

Status	Code	Meaning
401	`invalid_api_key`	The key is missing, malformed or unknown.
401	`key_revoked`	The key was revoked.
401	`key_expired`	The key's `expires_at` has passed.
403	`insufficient_permission`	The key lacks the permission for this operation.
403	`partner_key_not_allowed` / `org_key_not_allowed`	The key is on the wrong surface.
403	`org_suspended` / `org_closed`	The org is suspended or closed.
400	`tenant_required`	A partner key on the Content API without `X-Tenant-Id`.

All codes are listed in Error codes.

Next: Connect social accounts