Auth tokens
Agent tokens authenticate the CLI and SDK to your account. Create, use, rotate, and revoke them.
Every tunnel is tied to an account by an agent token. The CLI and Node SDK
read it from OSM_TOKEN; the relay verifies it on connect and authorizes the
tunnel against your plan limits.
Create a token
Sign in at app.osmrouter.com, open Tokens, and
create one. A token looks like osm_xxxxx. Copy it immediately — the full value
is shown only once.
export OSM_TOKEN=osm_xxxxx
osmrouter http 8080Exports are per-shell. A new terminal won't have OSM_TOKEN unless you add the
export to your shell profile (~/.zshrc, ~/.bashrc).
How the token is used
- The CLI/SDK sends the token to the relay when it dials out.
- The relay asks the control plane to verify the token and authorize the requested hostname against your account and plan.
- A revoked or malformed token is rejected before any tunnel comes up, with a branded error — no tunnel is created.
The token travels as agent metadata on the tunnel connection; it is never exposed to visitors of your tunnel.
Rotate and revoke
Treat a token like a password. Anyone who has it can open tunnels on your account.
- Rotate by creating a new token, switching your
OSM_TOKENto it, then deleting the old one. - Revoke a leaked token under Tokens → Revoke. Any agent still using it is rejected on its next connect.
Don't commit OSM_TOKEN to source control or bake it into client-side code.
Keep it in environment variables or a secrets manager.
Use multiple tokens
Create separate tokens per machine, per environment, or per CI job. Revoking one doesn't affect the others, so you can cut off a single laptop or pipeline without disrupting everything else.
Next steps
- CLI reference — every environment variable the client reads.
- REST API — authenticate API calls with the same token.