Documentation

Authentication

Workspace API keys and scopes, sessions, instance tokens and roles.

There are three ways to authenticate, for three different jobs.

CredentialHowUse it for
Workspace API key (sjk_...)Authorization: Bearer sjk_... on the native REST API (/api/v1/...)Your servers and scripts: create and connect instances, send messages, read history, manage webhooks
Session (cookie or session token)Browser cookie, or Authorization: Bearer <session token> for mobile appsThe console and mobile apps: anything acting as a signed-in person
Instance id + tokenIn the URL: /waInstance{id}/{method}/{token} (Green-compatible routes)Automation tools (Make, Zapier, n8n, spreadsheets) and existing Green API clients

Workspace API keysLive

API keys are for server-to-server use. Create one in the console under API keys (Owner or Admin). Each key has a name, the scopes you tick, and an optional expiry. The full key (sjk_<8 characters>_<43 characters>) is shown once, in the response that creates it. Only its SHA-256 is stored, so neither the key list nor any email can ever show it again. Lose it? Revoke it and create a new one.

Use a key
curl https://api.sendjade.com/api/v1/instances \
  -H "Authorization: Bearer $SENDJADE_API_KEY"

# create one with the API (Owner/Admin, signed-in session; keys cannot create keys)
POST https://api.sendjade.com/api/v1/apikeys   { "name": "Billing server", "scopes": ["instances:read", "messages:send"], "expiresInDays": 90 }
-> { "key": "sjk_a1b2c3d4_...", ... }     (shown once)

GET    https://api.sendjade.com/api/v1/apikeys          list: prefix, scopes, lastUsedAt, lastUsedIp, expiresAt, status
DELETE https://api.sendjade.com/api/v1/apikeys/{id}     revoke (immediate)
ScopeAllows
instances:readView instances, their status and settings (GET on /instances...)
instances:writeCreate, connect, reboot, log out and delete instances; request a pairing code
messages:sendSend messages, files, group messages and reactions; change chats, contacts, groups, statuses, the queue and opt-outs
messages:readRead message history, chats, contacts, groups and opt-outs
webhooks:manageCreate and manage webhooks
billing:readView the wallet balance and transactions
  • The scope a request needs is derived from its HTTP method and path. Write scopes do not imply read scopes: a key that creates instances also needs instances:read to fetch the QR code.
  • A key acts with the role its scopes imply (never Owner, never platform admin), and only inside its own workspace. Another workspace's ids answer 404.
  • Keys are refused on account routes (sign-in, support, notifications, billing writes, admin, key management): 403 api_key_not_allowed.
  • A wrong, revoked or expired key answers 401. A missing permission answers 403 missing_scope.
  • Last use (time and IP) is recorded at most once a minute and shown in the console. Creating or revoking a key emails and notifies the workspace owners and admins.

Sessions (console and mobile apps)Live

Browsers use a secure HttpOnly cookie. Mobile apps (and scripts that cannot hold an API key) ask for the same session as a bearer token by signing in with "client": "mobile". For long-lived servers prefer an API key: it is scoped, revocable and never expires with a password change.

Get a bearer token
curl -X POST https://api.sendjade.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"your-password","client":"mobile"}'

# response
{ "data": { "user": { "...": "..." }, "token": "<session token>" } }

# use it
curl https://api.sendjade.com/api/v1/instances -H "Authorization: Bearer <session token>"

Instance id + token (Green-compatible)Live

Every instance has a public idInstance and a secret apiTokenInstance. They go in the URL: /waInstance{idInstance}/{method}/{apiTokenInstance}. The token is shown once at creation (only its hash is stored), can be regenerated at any time, and can only ever act on its own instance. A wrong token and an unknown id return the same 401, so ids cannot be probed. Treat the whole URL as a secret and keep it out of logs and browser history.

RolesLive

RoleCan do
ViewerRead instances, messages, queue, state, webhooks and settings
MemberConnect, reboot, stop, read the QR code, send messages, poll notifications, manage groups and statuses
AdminCreate, log out and delete instances; rotate tokens; change settings; manage webhooks, opt-outs and API keys; clear queues
OwnerEverything in the workspace
Platform adminSendjade operators only: all workspaces

Email verificationLive

In production, creating and connecting instances requires a verified email. The API answers 403 email_unverified until you confirm the link we email you.