Client configuration

Token

You need an access token to connect. The format is AT_<token_id>_<secret>: token_id and secret are each 16 bytes encoded in hex (32 hex characters). Your admin creates tokens via the REST API (see REST API). Each token contains the following (permissions and metadata):


{
  "tenant_grants": 
  [
    {
      "tenant_ids": ["tenant1", "tenant2"],
      "allow_channels_pub": ["orders.#"],
      "allow_channels_sub": ["orders.#", "alerts.#"]
    },
    {
      "tenant_ids": ["tenant3"],
      "allow_channels_pub": ["notifications"],
      "allow_channels_sub": ["notifications", "status.#"]
    }
  ],
  "allow_ip_masks": ["192.168.1.0/24", "10.0.0.0/8"],
  "allow_regions": ["EU"],
  "allowed_ws_origin": ["https://app.example.com"],
  "expires_at": "2026-12-31T23:59:59Z",
  "description": "Token for production API access"
}

curl -X POST https://api.fastpubsub.com/v1/get-token \
  -H "Authorization: Bearer master_secret_123" \
  -H "Content-Type: application/json" \
  -d '
{
  "tenant_grants": 
  [
    {
      "tenant_ids": ["tenant1", "tenant2"],
      "allow_channels_pub": ["orders.#"],
      "allow_channels_sub": ["orders.#", "alerts.#"]
    }
  ],
  "allow_ip_masks": ["192.168.1.0/24"],
  "allow_regions": ["EU"],
  "allowed_ws_origin": ["https://app.example.com"],
  "expires_at": "2026-12-31T23:59:59Z",
  "description": "Token for production API access"
}'

tenant_grants — list of permission grants. Each grant has:
- tenant_ids — list of tenant names this grant applies to (e.g. ["tenant1", "tenant2"]). Publish and subscribe are only allowed for these tenants. Only exact tenant names are supported (no regex, no wildcards).
- allow_channels_pub — list of channel rules allowed for publish for these tenants. Although the server has an extended internal wildcard matcher, tokens use a restricted, non-ambiguous subset:
  - Exact channel: "a.b.c" — allows publishing only to that exact channel.
  - Prefix tree: "a.b.c.#" — allows publishing to "a.b.c" and to any sub-channel under it (any channel starting with "a.b.c.").
- allow_channels_sub — list of channel rules allowed for subscribe for these tenants. The same restricted pattern subset applies:
  - Exact channel: "a.b.c" — allows subscribing only to that exact channel.
  - Prefix tree: "a.b.c.#" — allows subscribing to "a.b.c" and to any sub-channel under it.
One token can have several grants with different tenant sets and different channel rules.
allow_ip_masks — optional. List of IP addresses or CIDR ranges; if non-empty, the connection is only accepted from client IPs that fall within these ranges (or match the exact IP when a single address is used). Examples: IPv4 single address 192.168.1.10, IPv4 range 192.168.1.0/24; IPv6 single ::1, IPv6 range 2001:db8::/32.
allow_regions — optional. Restricts where client authentication may be performed: the token is only accepted when the authentication request is handled in one of the listed regions. Example: ["US"] — authentication only on infrastructure in the United States; ["EU"] — only in the European Union (a token with ["EU"] is automatically rejected on a Swiss or UK node, which are not in the EU list). Currently only US and EU are supported; other regions may be added later or on request.
allowed_ws_origin — optional. Applies only to WebSocket: list of allowed HTTP Origin header values sent by the browser on connection. If non-empty, the WebSocket handshake is accepted only when Origin matches one of them. For the Quick protocol this field is ignored.
expires_at — expiry date and time (ISO 8601, e.g. 2026-12-31T23:59:59Z). After this time the token is no longer valid and cannot be used for authentication. You can also deactivate a token without revoking it immediately: via the refresh mechanism (see REST API), set a new expires_at in the past. Then authentication with that token fails, existing connections stay up, and the token is removed shortly. This allows graceful deactivation without forcing disconnects.
description — metadata set when the token is created (who created it and optional description); used for administration and listing.

Token channel pattern rules (restricted subset)

Allowed forms:

"a.b.c" (exact)
"a.b.c.#" (prefix tree; matches the base channel and any deeper channel)

.# is allowed only as the final suffix and must be preceded by a dot:

Valid: "orders.#", "eu.de.by.#"
Invalid: "orders#", "or#ders", "orders.#.created", "#"

Other wildcards (e.g. *, >, prefix#, regex) are not supported in tokens and will be rejected when creating a token.

Pass the token when opening the connection. For WebSocket: use the Authorization: Bearer AT_... header (server-side) or the Sec-WebSocket-Protocol subprotocol (browser). For gRPC: pass the token in metadata. See WebSocket API.

Endpoint

Use the WebSocket or gRPC URL from your operator, e.g. wss://ws.fastpubsub.com/ for WebSocket or https://api.example.com:443 for gRPC. The token is sent at connection time.

Tenant and channel

Every message is scoped by tenant and channel name. Writers and listeners must use the same tenant and channel to exchange messages. You can subscribe with wildcard patterns to match several channels (see Patterns & matching).

Limits

Tenant and channel values have size and character limits. See Limits.

See also

Permissions model — more details on token rules and how they interact with runtime subscriptions

Keyboard shortcuts

LowLatencyPubSub

Client configuration