Skip to content
Whatomate

Authentication

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

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

{
  "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

{
  "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

Authenticate and receive tokens.

Terminal window
POST /api/auth/login

Request Body

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

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

Get a new access token using your refresh token.

Terminal window
POST /api/auth/refresh

Request Body

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

Response

{
  "status": "success",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "expires_in": 3600
  }
}

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

{
  "organization_id": "uuid"
}

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

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

Token TypeDefault Expiration
Access Token1 hour
Refresh Token7 days