Authentication

WA-RS uses JWT (JSON Web Tokens) for API authentication. All API endpoints (except /health and /swagger-ui) require a valid JWT token.

Getting Your Token

When the server starts, it generates a superadmin JWT token and prints it to the console:

INFO wa_rs: ===========================================
INFO wa_rs: SUPERADMIN JWT TOKEN (save this!):
INFO wa_rs: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
INFO wa_rs: ===========================================

Save this token - you'll need it for all API requests.

Using the Token

Include the token in the Authorization header with the Bearer prefix:

curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  http://localhost:3000/api/v1/sessions

Request Examples

List Sessions

curl -X GET \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  http://localhost:3000/api/v1/sessions

Create Session

curl -X POST \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "my-session", "name": "My Account"}' \
  http://localhost:3000/api/v1/sessions

Error Responses

Missing Token

{
  "error": "Unauthorized",
  "message": "Missing or invalid Authorization header. Use: Bearer <token>"
}

Invalid Token

{
  "error": "Unauthorized",
  "message": "Invalid token format"
}

Expired Token

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

Custom JWT Secret

By default, WA-RS generates a random JWT secret. For production, set your own secret:

export JWT_SECRET=your-super-secure-secret-key

Or in .env:

JWT_SECRET=your-super-secure-secret-key

Token Structure

The JWT token contains:

{
  "sub": "superadmin",
  "role": "superadmin",
  "exp": 1798679117,
  "iat": 1767143117
}

Field	Description
sub	Subject (user identifier)
role	User role (must be "superadmin")
exp	Expiration timestamp
iat	Issued at timestamp

Public Endpoints

These endpoints don't require authentication:

Endpoint	Description
GET /health	Health check
GET /swagger-ui/*	Swagger UI
GET /api-docs/*	OpenAPI spec