Authentication

How WUTS authenticates requests with per-user Bearer tokens, the role hierarchy, and the platform master token.

WUTS authenticates every request with a Bearer token. The token is a UUID that belongs to a single user and identifies both the user and the tenant they belong to. There are no API keys, sessions, or cookies — just one header on every call.

curl https://api.wuts.com.br/status \
  -H "Authorization: Bearer e5f7ebbd-ed1f-47ea-b060-d9afd5c0076d"

The Authorization header

Tokens are sent only in the Authorization header. Query parameters, cookies, and form fields are never read — this keeps tokens out of logs and URLs.

Authorization: Bearer <token>

The preferred form is Bearer <token>. The scheme is matched case-insensitively, and a bare token with no Bearer prefix is also accepted, but you should always send the explicit Bearer prefix.

A token is a UUID v4 — 36 characters, e.g. e5f7ebbd-ed1f-47ea-b060-d9afd5c0076d. It is issued when the user is created and does not expire automatically. Because the token maps to a user, and the user belongs to a tenant, you never pass a tenant id — it is resolved from the token on the server.

Tenant isolation

Every authenticated request is automatically scoped to the caller's tenant. Users from one tenant can never read or write another tenant's devices, contacts, or messages. The only exception is the platform master token described in Super Admin endpoints, which operates across tenants.

Role hierarchy

A user's token carries one of three roles. The role decides which endpoints the user may call.

Role	What it can do
`admin`	Full control of the tenant: create and manage users, manage devices and webhooks, and call every tenant-scoped endpoint.
`manager`	Manage devices, view reports, and perform limited user management (view, update `active`, and the role changes allowed by the promotion rules). Cannot create new admins.
`user`	Operate their own data and their own devices. Cannot manage other users.

Endpoints that require a specific role enforce it server-side. An admin token is always accepted on role-gated routes — admin is a superset of manager and user. A token with an insufficient role receives 403 Insufficient permissions.

{ "error": "Insufficient permissions" }

How tokens are issued

1. Create a tenant and its first admin

A tenant and its first user are created together with POST /register. This endpoint is part of the Super Admin surface, so it is authenticated with the platform master token (see below), not a user token. The first user of a tenant is its admin.

curl -X POST https://api.wuts.com.br/register \
  -H "Authorization: Bearer <master-token>" \
  -H "Content-Type: application/json" \
  -d '{
        "tenant_name": "empresa_xyz",
        "email": "admin@empresa.com",
        "password": "SenhaForte123",
        "role": "admin",
        "webhook_url": "https://example.com/webhook"
      }'

email must be a valid address and password must be at least 6 characters. The optional webhook_url is stored and auto-configured when the first device connects — see Webhooks. The response returns the tenant, the admin user, and the admin's token.

{
  "success": true,
  "tenant": {
    "id": "91e05c67-8668-41a0-8bfb-c34d1c9d5a05",
    "name": "empresa_xyz",
    "created_at": "2025-07-01T09:45:59.734Z"
  },
  "user": {
    "id": "f30b657c-c365-49aa-a3fd-07326227950d",
    "tenant_id": "91e05c67-8668-41a0-8bfb-c34d1c9d5a05",
    "email": "admin@empresa.com",
    "role": "admin",
    "token": "e5f7ebbd-ed1f-47ea-b060-d9afd5c0076d",
    "active": true
  },
  "token": "e5f7ebbd-ed1f-47ea-b060-d9afd5c0076d"
}

Save the returned token — it is the admin's credential for every subsequent request.

2. Admins create more users

Once you have an admin token, create additional admin, manager, or user accounts inside the same tenant with POST /users. This route requires the admin role.

curl -X POST https://api.wuts.com.br/users \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
        "email": "operador@empresa.com",
        "password": "SenhaForte123",
        "role": "user"
      }'

The new user is returned with its own token in the 201 Created response. That token is the user's permanent credential. See User management and the API Reference for updating, promoting, and deactivating users.

There is no POST /login exchange. Each user's token is the credential — you provision it once at creation time and reuse it on every request.

Super Admin endpoints

A small set of platform-level operations sit outside any tenant and are protected by a single, separate master token configured on the platform. The master token is not a user token: it does not belong to a tenant, it bypasses tenant isolation, and it grants the super_admin role for these routes only.

Endpoint	Purpose
`POST /register`	Create a tenant and its first admin user.
`GET /tenants`	List every tenant on the platform.
`GET /global/tenants/:id`	Fetch a single tenant by id.
`DELETE /global/tenants/:id`	Delete a tenant and its data.

Pass the master token the same way, in the Authorization header:

curl https://api.wuts.com.br/tenants \
  -H "Authorization: Bearer <master-token>"

If the platform has Super Admin access disabled, these routes return 403. An incorrect master token returns 401 invalid master token.

{ "success": false, "error": "invalid master token" }

Authentication errors

Status	Meaning
`401`	Missing `Authorization` header, or the token is unknown / belongs to an inactive user.
`403`	Authenticated, but the role is insufficient for the endpoint (or Super Admin access is disabled).

{ "error": "Invalid token" }

See Errors for the full error model.

Security best practices

Treat every token like a password. Anyone holding a user token can act as that user inside their tenant; anyone holding the master token controls the entire platform.

Always call WUTS over HTTPS so tokens are never sent in the clear.
Keep tokens in environment variables or a secret manager — never commit them to source control or paste them into URLs.
Give each integration its own user with the least role it needs (user or manager), not an admin token.
Store the master token with the highest level of protection and use it only for the Super Admin endpoints above — never in client-side code or a shared integration.
Rotate tokens periodically. To revoke access, deactivate the user; their token stops working on the next request.

Next steps

Quickstart — go from zero to a sent message.
Connect a device — pair WhatsApp with your tenant.
Conventions — request/response shapes used across the API.

On this page