JWT Configuration

JSON Web Token authentication reference.

Configuration

{
  "jwt": {
    "secret": "{{env.JWT_SECRET}}"
  }
}

JWT Payload

Standard claims:

{
  "sub": "user-123",
  "role": "admin",
  "tenant_id": "tenant-456",
  "exp": 1704067200,
  "iat": 1704063600
}

Generate Token

npm run generate-jwt

Or programmatically:

import jwt from 'jsonwebtoken';

const token = jwt.sign(
  {
    sub: 'user-123',
    role: 'admin',
    tenant_id: 'tenant-456'
  },
  process.env.JWT_SECRET,
  { expiresIn: '1h' }
);

Protect Routes

{
  "path": "/admin/users",
  "method": "get",
  "requireAuth": true
}

Access Claims in Routes

{
  "data": {
    "user_id": "{{auth.sub}}",
    "role": "{{auth.role}}",
    "tenant_id": "{{auth.tenant_id}}"
  }
}

Request Header

curl -X GET http://localhost:3000/api/protected \
  -H "Authorization: Bearer <token>"

Error Responses

Missing Token

{
  "error": "Unauthorized",
  "message": "No authorization token provided"
}

Status: 401

Invalid Token

{
  "error": "Unauthorized",
  "message": "Invalid or expired token"
}

Status: 401

Expired Token

{
  "error": "Unauthorized",
  "message": "Token expired"
}

Status: 401

Best Practices

1. Use minimum 32-character secrets
2. Set appropriate expiration (1h recommended)
3. Include only necessary claims
4. Rotate secrets periodically
5. Use HTTPS in production