API Authentication

disaster-server uses JWT to protect business APIs. In production, /apis and /api routes use JWT middleware. dev mode may disable authentication for local debugging.

Public Endpoints

Endpoint	Purpose
GET /healthz	Health check
GET /readyz	Readiness check
POST /login	Login and obtain access/refresh tokens
POST /refresh_token	Exchange refresh token for a new access token
GET /openapi.yaml	OpenAPI YAML when Swagger is enabled
GET /openapi.json	OpenAPI JSON when Swagger is enabled
GET /swagger/	Swagger UI

Login

POST /login
Content-Type: application/json

{
  "username": "admin",
  "password": "Softc@1024"
}

This password applies only to a fresh installation that creates or backfills the built-in administrator. Existing administrator password hashes are stored in the disaster-system/disaster-server-users Secret and are not overwritten by a server upgrade. Change the password to an environment-specific value immediately after deployment through the user-management API.

Success response:

{
  "code": 0,
  "data": {
    "accessToken": "<jwt>",
    "refreshToken": "<jwt>",
    "expire": "2026-05-15T12:00:00+08:00",
    "userid": 1,
    "username": "admin"
  }
}

Call Business APIs

Authorization: Bearer <accessToken>

Example:

curl -H "Authorization: Bearer ${TOKEN}" \
  http://<server>/apis/disasterinstances.testudo.softcdata.com/v1/instances

Refresh Token

POST /refresh_token
Content-Type: application/json

{
  "refreshToken": "<refreshToken>"
}

The current implementation returns a new access token and does not rotate the refresh token.

Watch / WebSocket Token

Watch or WebSocket clients can pass tokens through:

Method	Notes
Authorization: Bearer <token>	Recommended
Sec-WebSocket-Protocol: <token>	For WebSocket clients with header limits
?token=<token>	Compatibility for EventSource/WebSocket clients

If the token contains characters unsuitable for Sec-WebSocket-Protocol, use query parameter or standard Authorization header.

Production Guidance

• Replace the default JWT secret.
• Change the built-in admin user's default password immediately after first login.
• Access APIs over HTTPS or controlled internal networks.
• Avoid leaking tokens in logs, URLs, or screenshots.
• Set an appropriate refresh token expiry.
• Keep OpenAPI/Swagger pages inside a controlled network.