Authentication
Use expiring Bearer tokens with read, send, and manage permissions. Session scoping limits access further.
Bearer tokens#
Create API keys in the authenticated workspace. Requests use an Authorization header containing the full token, including its tw_live_ prefix. Tokens expire after 90 days and are stored as hashes; only their prefix is shown after creation.
Browser login cookies are not API credentials. Keep tokens on your server or in a secret manager; do not embed them in public frontend JavaScript, repositories, screenshots, or support tickets.
Authorization: Bearer tw_live_YOUR_TOKENPermissions#
Combine scopes when your integration needs more than one. The API checks the operation’s required permission before accessing the resource.
| Scope | Allows |
|---|---|
| read | List your sessions, refresh status, read message states, and read available contacts, groups, and chats. |
| send | Queue text messages and paid advanced message operations, including group text, media and polls. It does not grant connection management. |
| manage | Create, start, stop, delete, or retrieve pairing QR codes for allowed sessions. It does not grant messaging or read permission. |
Session restrictions#
A key may cover all sessions in its own account or be bound to one session. A bound key cannot access another session or create a new one, even if it has manage permission.
Resources belonging to another customer remain unavailable regardless of your key’s scopes. Pairing QR codes require manage because they can authorize account access.
Rotate or revoke a key#
A key is not a guarantee of active service: verification, account restrictions, trial expiry, subscription state, and usage limits are checked separately.
- Create a replacement key with the permissions and session restriction your app needs.
- Deploy the replacement token to your application and verify its requests.
- Revoke the old key in the workspace. Revocation blocks new requests immediately.