Runtime tokens
Provision and rotate the FS_RUNTIME_TOKEN your backend reads — the single secret that drives bootstrap, verification, and metering.
Provision and rotate the FS_RUNTIME_TOKEN your backend reads — the single secret that drives bootstrap, verification, and metering.
A runtime token (prefix fsrt_) is the one secret your origin needs. From it
the @farthershore/backend SDK derives everything —
product and backend ids, the JWKS URL, the metering endpoint and credential,
verification config, and transport — at fartherShore.initFromEnv(). You set it
as FS_RUNTIME_TOKEN and nothing else.
import { fartherShore } from "@farthershore/backend";
// Reads process.env.FS_RUNTIME_TOKEN and bootstraps from it.
const fs = fartherShore.initFromEnv();
Tokens are minted with the farthershore backend tokens command group. The
plaintext value is shown once at create/rotate time — store it immediately
(a secret manager or your deploy platform's env). Lists never reveal the secret,
only its id, last-four, capabilities, and status.
farthershore backend tokens create <productId>
The output carries the field envVar: "FS_RUNTIME_TOKEN" and the new token
under result — copy it straight into your backend's environment:
export FS_RUNTIME_TOKEN="fsrt_live_…" # shown once; store it now
| Flag | Meaning |
|---|---|
--backend <backendId> | Bind the token to a specific backend. |
--env <environment> | Scope to a preview environment (name or id); omit for production. |
--kind <live|test> | Token kind; defaults from the env scope. |
--capabilities <list> | Comma-separated: gateway_verification, metering, health, tunnel. Omit to use the platform defaults. |
--meters <list> | Comma-separated allow-list of meter keys (default: all product meters). |
--routes <list> | Comma-separated allow-list of routes. |
Capabilities gate what the token may do. Use them to follow least privilege —
e.g. a tunnel backend must include tunnel, while a
direct backend that only reports response usage needs just
gateway_verification, metering, and health.
# A tunnel backend's token: include the tunnel capability.
farthershore backend tokens create <productId> \
--backend <backendId> \
--capabilities gateway_verification,metering,health,tunnel
# A least-privilege token scoped to one meter.
farthershore backend tokens create <productId> \
--backend <backendId> \
--capabilities metering --meters tokens_used
An unknown capability is rejected with UNKNOWN_RUNTIME_TOKEN_CAPABILITY. The
only valid values are gateway_verification, metering, health, and tunnel.
farthershore backend tokens list <productId>
Prints each token's id, last-four, capabilities, and status. Secrets are never
shown — use this to find the tokenId you need for a rotate or revoke.
Rotation mints a fresh secret carrying the same scope and revokes the old one. Use it on a schedule or after any suspected exposure. The new plaintext is returned once.
farthershore backend tokens rotate <productId> <tokenId>
Like create, the output carries envVar: "FS_RUNTIME_TOKEN" and the new
result. Deploy the new value, confirm the backend re-bootstraps cleanly, then
the old token is already revoked — there is no dual-validity window to clean up.
Because the SDK caches bootstrap config in memory, restart (or redeploy) your backend after rotating so it picks up the new token and re-bootstraps. A running process keeps using the secret it started with.
Revocation is immediate and irreversible. The backend using it stops verifying requests, so only revoke a token you have already replaced.
farthershore backend tokens revoke <productId> <tokenId> --yes
The --yes flag is required to confirm. Deleting a backend
(farthershore backend delete <productId> <backendId> --yes) also revokes that
backend's runtime tokens.
| Action | Command | Returns secret? |
|---|---|---|
| Create | backend tokens create <productId> [flags] | Yes (once) |
| List | backend tokens list <productId> | No |
| Rotate | backend tokens rotate <productId> <tokenId> | Yes (once) |
| Revoke | backend tokens revoke <productId> <tokenId> --yes | — |
Keep the token out of source control. It is the only credential that lets a process act as your backend, so treat it like a database password: inject it from the environment, rotate it periodically, and revoke immediately on exposure.
@Backend.tunnel capability.@farthershore/backend reference — the full SDK export surface.