Skip to content

Simulation Docs Login

This page explains how to access Swagger docs and authenticate requests in simulation.

Access the API docs

Use one of the following URLs:

  • Through Caddy (recommended): https://localhost/rest/docs
  • Direct REST server: http://localhost:8000/docs
  • The same Swagger page exposes both v1 and v2 endpoints (/api/v1/... and /api/v2/...).

Authenticate in Swagger

Most endpoints are protected and require a JWT bearer token.

  1. Call GET /rest/api/v2/auth/ with header:
  2. X-API-Key: admin (or user)
  3. Copy the token from the response body.
  4. In Swagger, click Authorize and enter:
  5. Bearer <token>
  6. Retry protected endpoints (for example GET /api/v2/skill/list/).

Quick curl example

# Get token
TOKEN=$(curl -ksS \
  -H "X-API-Key: admin" \
  "https://localhost/rest/api/v2/auth/" | jq -r '.token')

# Call a protected endpoint
curl -ksS \
  -H "Authorization: Bearer $TOKEN" \
  "https://localhost/rest/api/v2/skill/list/"

# Refresh the token for a long-running client
TOKEN=$(curl -iksS \
  -H "Authorization: Bearer $TOKEN" \
  "https://localhost/rest/api/v2/auth/refresh/" \
  | awk 'tolower($1) == "authorization:" {print $3}' \
  | tr -d '\r')

JWTs include an exp claim. Clients with persistent WebSocket or video connections should refresh before that time and then reconnect those transports with the refreshed token.

About command routes

Wizard commands are exposed as explicit standard endpoints:

  • POST /api/v2/commands/<command_name>/ for commands with a payload
  • GET /api/v2/commands/<command_name>/ for read-only no-payload commands
  • POST /api/v2/commands/<command_name>/ for action no-payload commands

API versions in simulation

  • v2 is the default API for command testing (/api/v2/commands/...).
  • v1 is kept for legacy generic routes (/api/v1/str/, /api/v1/dict/, /api/v1/get/{command}, etc.) during migration.
  • Legacy v1 generic responses include deprecation headers (Deprecation, Sunset, X-Legacy-Generic-Route).

Common errors

  • 401 Authorization header missing: bearer token not sent.
  • 403 Unauthorized access level: token role is insufficient.
  • 500 Internal Server Error: backend runtime error (check harmony container logs).