Threat model & best practices

This page lists practical security advice for using access tokens in production.

Threat model (what can go wrong)

• Token leak: someone gets a valid AT_... token (logs, browser storage, screenshots, copy/paste).
• Over-permissioned token: a token allows too many tenants or too broad channel roots.
• Origin bypass: a browser token is usable from an unexpected website if allowed_ws_origin is not restricted.
• Network misuse: a token is used from untrusted networks/IP ranges if allow_ip_masks is not restricted.
• Long-lived access: a token lives too long and becomes a “permanent key”.

Best practices

Rotate tokens

• Prefer short expiry (expires_at) for user-facing clients.
• Rotate tokens regularly for long-lived integrations.
• Automate refresh/replace flows on the client side.

Least privilege

• Grant only the tenants and channel roots that are needed.
• Avoid “one token for everything”. Split by service, environment, and role.
• Use channel roots that make capabilities obvious: pub.#, sys.#, admin.#, etc.

Protect browser clients

• Restrict allowed_ws_origin for browser tokens.
• Treat tokens as secrets. Do not store long-lived tokens in localStorage.
• Prefer a backend-minted short-lived token (exchange flow) for public clients.

Constrain where tokens can be used

• Use allow_ip_masks for server-to-server integrations.
• Use allow_regions if it matches your operational model.

Operational hygiene

• Never log full tokens (AT_...).
• Provide a fast revoke path for incident response (see REST API).
• Track which systems hold which tokens (ownership and purpose in description).

Related pages

• Tokens
• Permissions model
• Client configuration

Threat model & best practices