Log out a session (unpair the device)
Logs the session out of WhatsApp and **unlinks the device**, so the number is no longer attached. Requires the `manage` capability. **Destructive.** Unlike `:stop` (which keeps the pairing), logout severs the link: to use the number again you must pair it from scratch via QR or a pairing code. The session row itself remains — use `DELETE /sessions/{session}` to remove it entirely. **Idempotency.** Logging out a session that is already logged out / unpaired is a harmless no-op. The response returns the refreshed session so you can see its new status. **Errors.** `not_found` (404) — no such session in your organization. `unauthorized` (401) / `forbidden` (403) — credential / capability failures. Returns **200** with the refreshed session.
Send Authorization: Bearer <token>. The router accepts two kinds of token and tries each in turn: a frontend-minted login JWT (verified against the frontend JWKS; the person's org + role are read from it), or an api-key for a script/service (carrying a fixed set of gateway permissions). The bearerFormat: JWT label describes the person-login case.
In: header
Path Parameters
The session id — a session is one attached (or to-be-attached) WhatsApp number, scoped to your organization. A session in another organization is reported as not_found (404), never forbidden.
Response Body
application/json
application/json
curl -X POST "https://example.com/api/v1/sessions/sess_01HZX8K3M9:logout"{ "autoRead": false, "createdAt": 1719662400000, "createdByUserId": "user_01J9DEF...", "gatewayId": "gw-sg-1", "id": "01J9ZX8K2QHV0M3T6R7P4N5W8C", "isAdminSession": false, "label": "Support line", "lastConnectedAt": 1719662400000, "organizationId": "org_01J9ABC...", "phoneNumber": "6281234567890", "presenceTyping": true, "ratePerHour": 600, "ratePerMin": 20, "status": "working", "updatedAt": 1719662400000, "waJid": "6281234567890@s.whatsapp.net", "waLid": "205227043110953@lid"}{ "error": { "code": "not_found", "details": { "property1": null, "property2": null }, "message": "session not found" }}Get the current pairing QR code GET
Returns the QR code to scan from WhatsApp on the phone (Settings → Linked devices → Link a device) to attach a number to this session. Requires the `manage` capability. **Behavior.** Returns the raw QR code string in the JSON body. **Side effect.** If no code is ready yet, this endpoint *starts pairing* and returns `not_found` (404) until a code exists. QR codes are short-lived and refresh periodically; they also stream live over the event stream as `auth.qr` events, so the recommended pattern is to subscribe there and follow the codes as they rotate rather than polling. **Precondition.** The session must be unpaired — requesting a QR for an already-paired session returns an error. **Errors.** `not_found` (404) — no code ready yet (pairing was started) or session unknown. `unauthorized` (401) / `forbidden` (403) — credential / capability failures.
Restart a session POST
Stops and then starts the session — a reconnect that keeps the number paired. Requires the `manage` capability. Use this to recover a session that is stuck or in a failed state. The number stays attached throughout; no re-pairing is needed. **Async.** The reconnect proceeds in the background; the response returns the refreshed session row so you can observe its new status. **Errors.** `not_found` (404) — no such session in your organization. `unauthorized` (401) / `forbidden` (403) — credential / capability failures. Returns **200** with the refreshed session.