REST API

The REST API is used for token management, not for publishing or subscribing. Publish and subscribe use WebSocket or WebTransport (where your operator exposes it).

Base URL

e.g. https://api.example.com. All token endpoints are under /v1/.

Authentication

Requests use a master token in the header: Authorization: Bearer <master_token>. Only admins have the master token. Clients receive access tokens (format AT_...) created via this API.

Token TTL limit

Maximum token lifetime is 24 hours. The expires_at field must not exceed 24 hours from the current time. Requests with expires_at further in the future will be rejected with HTTP 400. This applies to both token creation (POST /v1/get-token) and TTL update (PUT /v1/refresh-token).

Endpoints

• POST /v1/get-token — Create a new access token. Body: right (permissions: tenant_grants, allow_ip_masks, allow_regions, allowed_ws_origin, expires_at), created_by, optional description. Response: { "token": "AT_..." }.
• DELETE /v1/revoke-token — Revoke a token. Body: { "token": "AT_..." }.
• PUT /v1/refresh-token — Extend token expiry. Body: token_id (8-byte hex id), new expires_at (ISO 8601). Max 24 hours from now.
• GET /v1/tokens — List tokens (metadata only, no secrets). Optional query: client_id.
• GET /ping — Health check; returns pong.

Request and response bodies are JSON. The API server can expose OpenAPI (Swagger) docs at /swagger-ui and the spec at /api-docs/openapi.json for the full schema.

Examples (curl)

Create a token:

curl -sS -X POST "https://api.example.com/v1/get-token" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <master_token>" \
  -d '{
    "right": {
      "tenant_grants": [
        {
          "tenant_ids": ["prod"],
          "allow_channels_pub": ["orders.#"],
          "allow_channels_sub": ["orders.#"]
        }
      ],
      "allow_ip_masks": [],
      "allow_regions": [],
      "allowed_ws_origin": [],
      "expires_at": "2026-12-31T23:59:59Z"
    },
    "created_by": "admin",
    "description": "Example token"
  }'

Revoke a token:

curl -sS -X DELETE "https://api.example.com/v1/revoke-token" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <master_token>" \
  -d '{ "token": "AT_..." }'

List tokens:

curl -sS "https://api.example.com/v1/tokens" \
  -H "Authorization: Bearer <master_token>"