REST API

The REST API is used for token management, not for publishing or subscribing. Publish and subscribe use WebSocket or gRPC.

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>"