Authentication & API keys

WhatsTIG has two separate authentication mechanisms:

Who	Mechanism	Used for
Your servers and integrations	Project API key (`Authorization: Bearer wt_live_...`)	The `/v1` API
People using the dashboard	Email + password session (optional TOTP 2FA), secure cookie	The dashboard only

Dashboard sessions never authenticate /v1, and API keys never authenticate the dashboard.

API keys

GET /v1/instances HTTP/1.1
Host: api.whatstig.com
Authorization: Bearer wt_live_k7d2m9q4ab_2bX9...

Format: wt_live_<keyId>_<secret>. The keyId part (e.g. shown as wt_live_k7d2m9q4ab in the dashboard) identifies the key; the secret is never stored by WhatsTIG, only an HMAC of it with a server-side pepper. The full key is shown once, when it is created or rotated.

Each key belongs to exactly one project. It can only see and change that project's instances, messages, media, webhooks and events. Resources of other projects respond 404 NOT_FOUND, exactly as if they did not exist.

Scopes

Scope	Allows
`instances:read`	List/get instances, status, QR
`instances:write`	Create, update, connect, reconnect, disconnect, logout, delete instances, create connect links
`messages:read`	List/get messages and their status history
`messages:send`	Send messages
`media:read` / `media:write`	Get / upload and import media
`webhooks:read` / `webhooks:write`	Read / manage webhook endpoints, deliveries, replay, test
`events:read`	Read the event log
`usage:read`	Read usage and plan limits
`keys:read` / `keys:write`	Manage API keys of the project (a key can only grant scopes it has)
`conversations:read` / `conversations:write`	Read / reply to and manage team inbox conversations
`contacts:read` / `contacts:write`	Read / manage contacts, tags, consent and imports
`campaigns:read` / `campaigns:write` / `campaigns:launch`	Read / manage segments and campaigns / launch them
`leads:read` / `leads:write`	Read / capture, update, assign and convert CRM leads; notes and tasks
`deals:read` / `deals:write`	Read / manage deals and the pipeline board
`companies:read` / `companies:write`	Read / manage companies
`crm:admin`	CRM settings, pipelines, custom fields, scoring and assignment rules, lead forms and links

A request without the needed scope fails with 403 INSUFFICIENT_SCOPE and details.required naming the scope.

Managing keys

Dashboard: Project → API keys (create with scopes, rotate, revoke).
API (needs keys:write): POST /v1/keys, GET /v1/keys, DELETE /v1/keys/{id} (revoke), POST /v1/keys/{id}/rotate.

Revocation takes effect immediately on every API server. Rotation issues a new key with the same name and scopes and revokes the old one; deploy the new key first if you need zero downtime (create a second key, switch, then revoke the first).

Rules

Keep keys on servers. Never ship a key to a browser, mobile app or desktop client. If your product's frontend needs to show a QR code, fetch it through your own backend, or use a hosted connect link.
Use one key per integration/environment so you can revoke independently.
Grant the minimum scopes. A notification service usually needs only messages:send and messages:read.

Errors

Status	Code	Meaning
401	`UNAUTHENTICATED`	Missing, malformed, unknown, revoked or expired key
403	`INSUFFICIENT_SCOPE`	Key lacks the scope for this operation
403	`FORBIDDEN`	The organization or project is not active

Dashboard sessions (for completeness)

Dashboard users sign up with email and password (minimum 10 characters), must verify their email, and can enable TOTP two-factor authentication in Organization settings. Sessions last 7 days and are stored server-side; cookies are HttpOnly, SameSite=Lax and Secure in production. Cookie-authenticated state-changing requests must come from the dashboard origin (Origin check) as CSRF protection.