REST API

REST is for token administration and edge ping. Publish and subscribe use WebSocket or WebTransport.

Base URL — the selected edge api_base from SDK discovery. Do not hard-code a single global host unless Cockpit gives you one.

Auth — Authorization: Bearer <master_token> on token routes. GET /ping has no auth.

TTL — access token expires_at must be within 24 hours.

Endpoints

Method	Path	Purpose
`GET`	`/ping`	Latency probe for edge selection. Returns a small body (pong).
`POST`	`/v1/get-token`	Create an access token.
`PUT`	`/v1/refresh-token`	Extend TTL (`token_id` + `expires_at`).
`DELETE`	`/v1/revoke-token`	Revoke a full `AT_...`.

Some edges also expose OpenAPI at /swagger-ui and /api-docs/openapi.json. Prefer the SDK helpers over copying JSON by hand.

Create token (curl)

curl -sS -X POST "$API_BASE/v1/get-token" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $FPS_MASTER_TOKEN" \
  -d '{
    "created_by": "docs-example",
    "description": "demo",
    "right": {
      "tenant_grants": [
        {
          "tenant_ids": ["app"],
          "allow_channels_pub": ["public.#"],
          "allow_channels_sub": ["public.#"]
        }
      ],
      "allow_ip_masks": [],
      "allow_regions": [],
      "allowed_ws_origin": [],
      "allow_protocols": ["websocket", "webtransport"],
      "ingress_kb_per_sec": 64,
      "egress_kb_per_sec": 64,
      "expires_at": "2026-08-24T12:00:00Z"
    }
  }'

Response includes { "token": "AT_..." }.

If the master token has a tenant_prefix (for example paint.), the server prepends it to each tenant_ids value that does not already start with that prefix. The access token stores the physical name. Use that name in publish/subscribe.

allow_ip_masks on the master token (Cockpit) restrict which IPs may call these REST routes. allow_ip_masks inside right still restrict the access-token socket.

allow_protocols, ingress_kb_per_sec, and egress_kb_per_sec may be omitted. Omit allow_protocols to allow both transports. Omit the KB/s fields to use the edge default (typically 8).

Set expires_at relative to now (the SDK accepts +1h). A date a year in the future is rejected.

Refresh

curl -sS -X PUT "$API_BASE/v1/refresh-token" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $FPS_MASTER_TOKEN" \
  -d '{ "token_id": "<hex id>", "expires_at": "2026-08-24T12:00:00Z" }'

Revoke

curl -sS -X DELETE "$API_BASE/v1/revoke-token" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $FPS_MASTER_TOKEN" \
  -d '{ "token": "AT_..." }'

Errors

Typical HTTP statuses: 400 invalid body, 401 bad master token, 403 master-token IP not allowed, 404 unknown token id.

See Error codes.

Keyboard shortcuts