JWT Authentication - GaiterGuard

Overview

JWT (JSON Web Token) authentication is used for dashboard users to manage agents, services, and approval workflows. GaiterGuard uses a dual-token system:

Access Token: Short-lived (15 minutes) for API requests
Refresh Token: Long-lived (7 days) for obtaining new access tokens

Token Configuration

From /home/daytona/workspace/source/backend/src/config/env.ts:26-27:

JWT_ACCESS_EXPIRY: 15m (15 minutes)
JWT_REFRESH_EXPIRY: 7d (7 days)

Authentication Endpoints

Register User

Create a new dashboard user account.

curl -X POST https://api.gaiterguard.com/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securePassword123"
  }'

Request Body

string

required

Valid email address. Must match format: /^[^\s@]+@[^\s@]+\.[^\s@]+$/

password

string

required

Password with minimum 8 characters. Hashed using Argon2id (memory cost: 65536, time cost: 2).

Response Fields

user

object

The created user record (password hash excluded)

number

Unique user identifier

string

User’s email address

Error Responses

Email Already Exists (409 Conflict)

{
  "error": "User with this email already exists",
  "statusCode": 409
}

Validation Error (400 Bad Request)

{
  "error": "Password must be at least 8 characters long",
  "statusCode": 400
}

Authenticate with email and password to receive access and refresh tokens.

curl -X POST https://api.gaiterguard.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securePassword123"
  }'

Request Body

string

required

User’s registered email address

password

string

required

User’s password

Response Fields

accessToken

string

JWT access token valid for 15 minutes. Use in Authorization: Bearer {token} header.

refreshToken

string

JWT refresh token valid for 7 days. Use to obtain new access tokens. Stored as hashed value in database.

user

object

Authenticated user information

Error Responses

Invalid Credentials (401 Unauthorized)

{
  "error": "Invalid credentials",
  "statusCode": 401
}

Returned when:

Email doesn’t exist in database
Password verification fails

Refresh Access Token

Exchange a valid refresh token for a new access + refresh token pair. Implements token rotation - the old refresh token is invalidated.

curl -X POST https://api.gaiterguard.com/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

Request Body

refreshToken

string

required

Valid refresh token from login or previous refresh

Response Fields

accessToken

string

New JWT access token valid for 15 minutes

refreshToken

string

New JWT refresh token valid for 7 days. The old refresh token is deleted from database.

Token Rotation Flow

From /home/daytona/workspace/source/backend/src/services/auth.service.ts:135-196:

Verify refresh token JWT signature
Extract user ID from token
Query refresh_tokens table for matching hash
Delete old refresh token (rotation)
Generate new access + refresh token pair
Store new refresh token hash in database
Return new tokens

Error Responses

Invalid Refresh Token (401 Unauthorized)

{
  "error": "Invalid refresh token",
  "statusCode": 401
}

Returned when:

Token signature verification fails
Token is expired
Token hash not found in database
Token already used (due to rotation)

Get Current User

Retrieve authenticated user information.

curl https://api.gaiterguard.com/auth/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Headers

Authorization

string

required

Bearer token format: Bearer YOUR_ACCESS_TOKEN

Response Fields

user

object

Current user information

number

User ID

string

User email

createdAt

string

ISO 8601 timestamp of account creation

Using JWT Tokens

Making Authenticated Requests

Include the access token in the Authorization header:

curl https://api.gaiterguard.com/agents \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Access Token Expiry Handling

Implement automatic token refresh when access token expires:

let accessToken = 'YOUR_ACCESS_TOKEN';
let refreshToken = 'YOUR_REFRESH_TOKEN';

async function makeAuthenticatedRequest(url) {
  let response = await fetch(url, {
    headers: { 'Authorization': `Bearer ${accessToken}` }
  });
  
  // Access token expired - refresh it
  if (response.status === 401) {
    const refreshResponse = await fetch('https://api.gaiterguard.com/auth/refresh', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ refreshToken })
    });
    
    const tokens = await refreshResponse.json();
    accessToken = tokens.accessToken;
    refreshToken = tokens.refreshToken; // Store new refresh token
    
    // Retry original request with new token
    response = await fetch(url, {
      headers: { 'Authorization': `Bearer ${accessToken}` }
    });
  }
  
  return response.json();
}

JWT Token Structure

Access Token

Generated by /home/daytona/workspace/source/backend/src/utils/jwt.ts:36-44:

Decoded Payload

{
  "sub": "10",           // User ID as string
  "iat": 1709460000,     // Issued at (Unix timestamp)
  "exp": 1709460900      // Expires at (iat + 15 minutes)
}

Algorithm: HS256 (HMAC-SHA256)
No type claim (distinguishes from refresh tokens)

Refresh Token

Generated by /home/daytona/workspace/source/backend/src/utils/jwt.ts:51-62:

Decoded Payload

{
  "sub": "10",           // User ID as string
  "type": "refresh",     // Token type identifier
  "iat": 1709460000,     // Issued at
  "exp": 1710064800      // Expires at (iat + 7 days)
}

Algorithm: HS256
Includes type: "refresh" claim for validation

Authentication Middleware

The requireAuth middleware (from backend/src/middleware/auth.ts:29) protects dashboard routes:

Extract Authorization header
Validate Bearer prefix format
Extract token after prefix
Verify token signature and expiry using jose library
Extract user ID from sub claim
Return { userId } for route handlers

Protected Routes

All agent management endpoints require JWT authentication:

POST /agents - Create agent
GET /agents - List agents
GET /agents/:id - Get agent details
PUT /agents/:id - Update agent
DELETE /agents/:id - Delete agent
PUT /agents/:id/services - Update agent services

Error Responses

Missing Authorization Header

{
  "error": "Missing authorization header",
  "statusCode": 401
}

Invalid Header Format

{
  "error": "Invalid authorization header format",
  "statusCode": 401
}

The header must start with Bearer (note the space).

Invalid or Expired Token

{
  "error": "Invalid or expired token",
  "statusCode": 401
}

Returned when:

Token signature verification fails
Token is expired
Token is malformed

Security Features

Password Hashing

Passwords are hashed using Argon2id with strong parameters:

Memory cost: 65536 KB
Time cost: 2 iterations
Built-in salt generation

Implementation: backend/src/services/auth.service.ts:54-58

Token Rotation

Refresh tokens are single-use. Each refresh operation:

Deletes the old refresh token from database
Issues a new refresh token
Prevents token replay attacks

Implementation: backend/src/services/auth.service.ts:176

Token Storage

Refresh tokens stored as hashed values in database
Access tokens are stateless (not stored)
Tokens use HS256 algorithm with secret key

Short-Lived Access Tokens

15-minute access token expiry minimizes exposure window if token is compromised. Use refresh tokens to obtain new access tokens.

Best Practices

Store Tokens Securely

Use secure HTTP-only cookies for web apps
Store in encrypted storage on mobile
Never expose tokens in URLs or logs

Handle Token Expiry Gracefully

Implement automatic refresh on 401 errors
Pre-emptively refresh before expiry
Clear tokens on logout

Use HTTPS

Always transmit tokens over HTTPS to prevent interception

Implementation Reference

Source code locations:

Auth routes: backend/src/routes/auth.ts
Auth service: backend/src/services/auth.service.ts
JWT utilities: backend/src/utils/jwt.ts
Auth middleware: backend/src/middleware/auth.ts:29
Config: backend/src/config/env.ts

Authentication

Agent Endpoints

Dashboard Endpoints

Reference

Documentation Index

​Overview

​Token Configuration

​Authentication Endpoints

​Register User

​Request Body

​Response Fields

​Error Responses

​Login

​Request Body

​Response Fields

​Error Responses

​Refresh Access Token

​Request Body

​Response Fields

​Token Rotation Flow

​Error Responses

​Get Current User

​Headers

​Response Fields

​Using JWT Tokens

​Making Authenticated Requests

​Access Token Expiry Handling

​JWT Token Structure

​Access Token

​Refresh Token

​Authentication Middleware

​Protected Routes

​Error Responses

​Missing Authorization Header

​Invalid Header Format

​Invalid or Expired Token

​Security Features

​Best Practices

Store Tokens Securely

Handle Token Expiry Gracefully

Use HTTPS

​Implementation Reference

Build docs developers (and LLMs) love

Overview

Token Configuration

Authentication Endpoints

Register User

Request Body

Response Fields

Error Responses

Login

Request Body

Response Fields

Error Responses

Refresh Access Token

Request Body

Response Fields

Token Rotation Flow

Error Responses

Get Current User

Headers

Response Fields

Using JWT Tokens

Making Authenticated Requests

Access Token Expiry Handling

JWT Token Structure

Access Token

Refresh Token

Authentication Middleware

Protected Routes

Error Responses

Missing Authorization Header

Invalid Header Format

Invalid or Expired Token

Security Features

Best Practices

Implementation Reference