Authentication
Workspace API keys and scopes, sessions, instance tokens and roles.
There are three ways to authenticate, for three different jobs.
| Credential | How | Use 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 apps | The console and mobile apps: anything acting as a signed-in person |
| Instance id + token | In 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.
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)| Scope | Allows |
|---|---|
instances:read | View instances, their status and settings (GET on /instances...) |
instances:write | Create, connect, reboot, log out and delete instances; request a pairing code |
messages:send | Send messages, files, group messages and reactions; change chats, contacts, groups, statuses, the queue and opt-outs |
messages:read | Read message history, chats, contacts, groups and opt-outs |
webhooks:manage | Create and manage webhooks |
billing:read | View 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:readto 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 answers403 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.
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
| Role | Can do |
|---|---|
| Viewer | Read instances, messages, queue, state, webhooks and settings |
| Member | Connect, reboot, stop, read the QR code, send messages, poll notifications, manage groups and statuses |
| Admin | Create, log out and delete instances; rotate tokens; change settings; manage webhooks, opt-outs and API keys; clear queues |
| Owner | Everything in the workspace |
| Platform admin | Sendjade 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.