Authentication

Overview

CloudWA supports two authentication methods:

1. JWT Tokens (Cookies or Header) - For user sessions and frontend applications
2. API Keys - For server-to-server integrations and automation

After logging in or registering, the server sets three secure cookies:

• whm_access - Secure, httpOnly cookie containing the short-lived access token.
• whm_refresh - Secure, httpOnly cookie containing the refresh token. Scoped to /api/auth/refresh for security.
• whm_csrf - A JavaScript-readable cookie containing a random CSRF token to prevent cross-site request forgery.

Alternatively, for headless clients or API integrations, you can include the access token in the Authorization: Bearer <token> header or use an API key in the X-API-Key header.

Register

Create a new user account within an existing organization. Registration requires an organization_id, which is typically provided via an invitation link.

Note

If the email already exists and the password matches, the user is added to the organization as a member instead of creating a new account.

POST /api/auth/register

Request Body

{
  "email": "user@example.com",
  "password": "securepassword123",
  "full_name": "John Doe",
  "organization_id": "uuid"
}

Field	Type	Required	Description
email	string	Yes	User’s email address
password	string	Yes	Minimum 12 characters
full_name	string	Yes	Display name
organization_id	string	Yes	UUID of the organization to join

Response

The response body contains user information and the token expiration details, while the actual JWT tokens are set as secure HTTP cookies (whm_access and whm_refresh).

{
  "status": "success",
  "data": {
    "expires_in": 3600,
    "user": {
      "id": "uuid",
      "organization_id": "uuid",
      "email": "user@example.com",
      "full_name": "John Doe",
      "role_id": "uuid",
      "is_active": true,
      "is_available": true,
      "is_super_admin": false,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z",
      "role": {
        "id": "uuid",
        "name": "agent",
        "description": "Standard Agent role"
      }
    }
  }
}

Login

Authenticate and receive tokens via cookies.

POST /api/auth/login

Request Body

{
  "email": "user@example.com",
  "password": "securepassword123"
}

Response

The response body contains user information and token expiration details. The JWT access and refresh tokens are set via secure, httpOnly cookies.

{
  "status": "success",
  "data": {
    "expires_in": 3600,
    "user": {
      "id": "uuid",
      "organization_id": "uuid",
      "email": "user@example.com",
      "full_name": "John Doe",
      "role_id": "uuid",
      "is_active": true,
      "is_available": true,
      "is_super_admin": false,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  }
}

Refresh Token

Get a new access token using your refresh token. The server rotates the refresh token upon consumption (refresh token rotation).

POST /api/auth/refresh

Request Body

If the client does not send cookies (e.g. headless scripts), the refresh token can optionally be provided in the request body:

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}

Response

Returns new tokens as secure cookies and the user metadata.

{
  "status": "success",
  "data": {
    "expires_in": 3600,
    "user": {
      "id": "uuid",
      "organization_id": "uuid",
      "email": "user@example.com",
      "full_name": "John Doe",
      "role_id": "uuid",
      "is_active": true,
      "is_available": true,
      "is_super_admin": false,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  }
}

Switch Organization

Switch the current user’s active organization. Returns new tokens scoped to the target organization with the user’s org-specific role and permissions.

Note

Non-super-admin users must be a member of the target organization. Super admins can switch to any organization.

POST /api/auth/switch-org

Request Body

{
  "organization_id": "uuid"
}

Response

The response body returns updated details of the user scoped to the new organization, along with new access and refresh cookies.

{
  "status": "success",
  "data": {
    "expires_in": 3600,
    "user": {
      "id": "uuid",
      "organization_id": "uuid",
      "email": "user@example.com",
      "full_name": "John Doe",
      "role_id": "uuid",
      "is_active": true,
      "is_available": true,
      "is_super_admin": false,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z",
      "role": {
        "id": "uuid",
        "name": "agent",
        "description": "Standard Agent role",
        "permissions": [
          { "resource": "contacts", "action": "read" },
          { "resource": "messages", "action": "read" }
        ]
      }
    }
  }
}

Logout

Log out the current user session. This endpoint invalidates the user’s refresh token inside the Redis store and clears all set authentication cookies.

POST /api/auth/logout

Request Body

If cookies are not used, the client can optionally specify the refresh token to invalidate:

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}

Response

{
  "status": "success",
  "data": {
    "status": "logged_out"
  }
}

WebSocket Authentication

Get a short-lived single-use JWT token for authenticating WebSocket connections. Since secure HTTP-only cookies cannot be accessed by client-side JavaScript, this endpoint provides a safe way to retrieve a token to pass via query parameters when establishing a WebSocket connection.

GET /api/auth/ws-token

Response

{
  "status": "success",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs..."
  }
}

Single Sign-On (SSO)

CloudWA supports Single Sign-On (SSO) using OAuth2/OIDC. This allows users to authenticate using external identity providers such as Google, Microsoft, GitHub, Facebook, or a custom OIDC provider.

List Public SSO Providers

Retrieve enabled SSO providers for displaying login buttons on the sign-in page.

GET /api/auth/sso/providers

Response

{
  "status": "success",
  "data": [
    {
      "provider": "google",
      "name": "Google"
    },
    {
      "provider": "github",
      "name": "GitHub"
    }
  ]
}

Initiate SSO Flow

Start the OAuth2 login flow for a specific provider. This endpoint generates a secure state token and redirects the user to the provider’s authorization page.

GET /api/auth/sso/{provider}/init

Path Parameters

Parameter	Type	Required	Description
provider	string	Yes	The identity provider name: google, microsoft, github, facebook, or custom

SSO Callback

Handle the redirect callback from the identity provider after the user authorizes access.

GET /api/auth/sso/{provider}/callback

Path Parameters

Parameter	Type	Required	Description
provider	string	Yes	The identity provider name: google, microsoft, github, facebook, or custom

Query Parameters

Parameter	Type	Required	Description
code	string	Yes (on success)	The authorization code returned by the provider
state	string	Yes	The state nonce used to verify request integrity and prevent CSRF
error	string	No (on failure)	The error code if authorization failed
error_description	string	No (on failure)	A description of why the authorization failed

Using Tokens

Include the access token in the Authorization header for all protected API requests:

curl -X GET "https://dashboard.cloudwa.net/api/contacts" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Token Expiration

Token Type	Default Expiration
Access Token	1 hour
Refresh Token	7 days

Caution

Store tokens securely. Never expose tokens in client-side code or version control.