Skip to content
Whatomate

Authentication

Overview

Section titled “Overview”

Whatomate supports two authentication methods:

  1. JWT Tokens - For user sessions and frontend applications
  2. API Keys - For server-to-server integrations and automation

After logging in, you receive an access token and refresh token. Include the access token in the Authorization header for all protected API requests. Alternatively, use an API key in the X-API-Key header.

Register

Section titled “Register”

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

Terminal window
POST /api/auth/register

Request Body

Section titled “Request Body”
{
  "email": "user@example.com",
  "password": "securepassword123",
  "full_name": "John Doe",
  "organization_id": "uuid"
}
FieldTypeRequiredDescription
emailstringYesUser’s email address
passwordstringYesMinimum 8 characters
full_namestringYesDisplay name
organization_idstringYesUUID of the organization to join

Response

Section titled “Response”
{
  "status": "success",
  "data": {
    "user": {
      "id": "uuid",
      "email": "user@example.com",
      "full_name": "John Doe",
      "organization_id": "uuid",
      "role": {
        "id": "uuid",
        "name": "agent"
      }
    },
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "expires_in": 3600
  }
}

Login

Section titled “Login”

Authenticate and receive tokens.

Terminal window
POST /api/auth/login

Request Body

Section titled “Request Body”
{
  "email": "user@example.com",
  "password": "securepassword123"
}

Response

Section titled “Response”
{
  "status": "success",
  "data": {
    "user": {
      "id": "uuid",
      "email": "user@example.com",
      "name": "John Doe"
    },
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "expires_in": 3600
  }
}

Refresh Token

Section titled “Refresh Token”

Get a new access token using your refresh token.

Terminal window
POST /api/auth/refresh

Request Body

Section titled “Request Body”
{
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}

Response

Section titled “Response”
{
  "status": "success",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "expires_in": 3600
  }
}

Switch Organization

Section titled “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.

Terminal window
POST /api/auth/switch-org

Request Body

Section titled “Request Body”
{
  "organization_id": "uuid"
}

Response

Section titled “Response”
{
  "status": "success",
  "data": {
    "user": {
      "id": "uuid",
      "email": "user@example.com",
      "full_name": "John Doe",
      "organization_id": "uuid",
      "role": {
        "id": "uuid",
        "name": "agent",
        "permissions": [
          { "resource": "contacts", "action": "read" },
          { "resource": "messages", "action": "read" }
        ]
      }
    },
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "expires_in": 3600
  }
}

Using Tokens

Section titled “Using Tokens”

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

Terminal window
curl -X GET "http://your-server:8080/api/contacts" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Token Expiration

Section titled “Token Expiration”
Token TypeDefault Expiration
Access Token1 hour
Refresh Token7 days