Authentication

Jack uses JWT (JSON Web Tokens) for API authentication. This page explains how to obtain and use tokens.

Overview

All API requests (except login) require an Authorization header with a valid JWT token:

Authorization: Bearer <your-jwt-token>

Obtaining a Token

Get a token by authenticating with valid credentials:

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

{
  "email": "[email protected]",
  "password": "your-password"
}

Response:

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "expiresAt": "2024-01-15T12:00:00Z",
    "user": {
      "id": "staff-123",
      "name": "John Smith",
      "email": "[email protected]",
      "role": "staff"
    }
  }
}

Using the Token

Include the token in all subsequent requests:

GET /api/v1/conversations
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json

Token Expiration

Tokens expire after 24 hours by default. The expiration time is included in the login response.

When a token expires, you'll receive:

{
  "success": false,
  "error": {
    "code": "TOKEN_EXPIRED",
    "message": "Your session has expired. Please login again."
  }
}

Refreshing Tokens

Refresh a token before it expires:

POST /api/v1/auth/refresh
Authorization: Bearer <current-token>

Response includes a new token with extended expiration.

Logging Out

Invalidate a token:

POST /api/v1/auth/logout
Authorization: Bearer <token-to-invalidate>

User Roles

Tokens include the user's role, which determines API access:

API Keys (Coming Soon)

For server-to-server integrations, API keys provide non-expiring authentication. This feature is planned for a future release.

Security Best Practices

• Store tokens securely — Never expose tokens in URLs or client-side code
• Use HTTPS — Always use encrypted connections
• Rotate secrets — Change JWT_SECRET periodically
• Minimize token lifetime — Shorter expiration = smaller attack window
• Validate on server — Never trust client-side token validation alone

Authentication Errors