Authentication

The Appilot API uses JWT (JSON Web Tokens) for authentication. Every request must include a valid token.

Obtaining a token

Login

POST /api/auth/login
Content-Type: application/json

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

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "name": "User Name"
  }
}

Using the token

Include the token in the Authorization header:

GET /api/knowledge
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Organization context

The JWT token includes the user's active organization context. All API calls are automatically scoped to this organization.

To switch organizations (for users with multiple org memberships), use:

POST /api/auth/switch-organization
Authorization: Bearer <token>
Content-Type: application/json

{
  "organizationId": "target-org-uuid"
}

This returns a new token with the updated organization context.

Widget API Key authentication

The Embeddable Widget uses a different authentication mechanism — Widget API Keys instead of JWT:

POST /widget/message
X-Widget-Key: wk_live_a1b2c3d4e5f6...
X-Widget-Session: ws_session_id_here
Content-Type: application/json

{
  "message": "How do I fill out this field?"
}

Widget API keys:

• Start with wk_live_ (production, domain-bound) or wk_test_ (development, no domain check)
• Identify the organization automatically (no organizationId needed)
• Are validated against allowed domains (Origin / Referer header)
• Have per-key rate limiting

Generate widget API keys in the Backoffice under Settings -> Widget Integration.

Token lifecycle

• Tokens are valid for a configurable duration (default: 24 hours)
• Tokens include: user ID, email, role, active organization ID
• Expired tokens return 401 Unauthorized

Roles

Role	Access
user	Basic access — chat, view knowledge, create requests
admin	Full organization management — knowledge, domains, users
super_admin	Platform-wide access (Platform Admin only)