Runtime tokens

A runtime token (fsrt_…) authenticates your running backend to Farther Shore. @farthershore/backend reads it from FS_RUNTIME_TOKEN to fetch bootstrap configuration, verify gateway requests, report health, and report configured meters. It is not a subscriber API key or a CLI login credential.

Persisted-kind upgrade#

The persisted-kind upgrade revokes every existing runtime token created before the migration, and its stored authentication hash is destroyed. Those tokens cannot be recovered and must be reissued. Create a replacement for each deployment, replace FS_RUNTIME_TOKEN in the host, and restart or redeploy it. The cutover does not infer continuing live or test authority from an old token's environment scope.

Create the backend row first#

A runtime token is scoped to backend rows. Register the backend with farthershore backend create before minting its token; a token created against an environment that has no backend row yet has nothing to resolve. When an environment has more than one backend, pass --backend <backend-id> so the token resolves to the intended row rather than depending on the environment's backend set staying singular.

Choose the deployment scope#

The recommended default for one deployment serving the same business across Main and previews is a business-scoped token:

farthershore backend tokens create my-business --format json --idempotency-key <persisted-backend-tokens-create-attempt-key>

The bootstrap response supplies every backend id the deployment may serve, so request verification remains bound to the business while accepting the signed, environment-specific backend id. The token does not grant access to another business.

Use a narrower scope when deployment isolation requires it:

# All backends in one preview environment.
farthershore backend tokens create my-business \
  --env staging \
  --idempotency-key <persisted-backend-tokens-create-attempt-key> \
  --format json

# One backend row.
farthershore backend tokens create my-business \
  --backend <backend-id> \
  --idempotency-key <persisted-backend-tokens-create-attempt-key> \
  --format json

Operations and meter restrictions#

The default operations are:

• gateway_verification
• metering
• health

Add tunnel for an embedded tunnel backend. You can also restrict dynamic usage to named meters or routes:

farthershore backend tokens create my-business \
  --operations gateway_verification,metering,health,tunnel \
  --meters tokens,compute_seconds \
  --routes post-v1-jobs \
  --idempotency-key <persisted-backend-tokens-create-attempt-key> \
  --format json

An empty meter or route allowlist means all corresponding meters or routes in the token's business/backend scope. A route-scoped token requires a matching route id on background metering events.

Secret delivery#

The plaintext token is returned once at creation or rotation. Store it directly as FS_RUNTIME_TOKEN in the deployment platform's secret manager. Do not put it in the repository, a Docker image, build arguments, logs, or frontend variables.

# Metadata only; plaintext tokens are never listed again.
farthershore backend tokens list my-business --format json

The list includes the persisted kind (live or test) so an operator can verify the runtime classification without seeing the secret.

Neither backend list nor backend tokens list accepts --env: both are business-wide reads. Filter on each returned row's environment rather than expecting a flag.

When infrastructure is described declaratively, keep the mint separate from the delivery: the CLI mints the one-time value and the infrastructure tool writes it into that environment's secret store as a sensitive variable. See Infrastructure with OpenTofu.

Most hosts inject secrets when a process starts. Restart or redeploy after changing FS_RUNTIME_TOKEN; a running SDK instance keeps its bootstrapped credential and configuration.

Rotation semantics#

backend tokens rotate creates a successor with the same scope and then marks the old token revoked immediately. There is no overlap window:

farthershore backend tokens rotate my-business <token-id> --format json --idempotency-key <persisted-backend-tokens-rotate-attempt-key>

That hard cutover is useful for a suspected leak, but it can interrupt running replicas that still hold the old value. Replace the secret and restart or redeploy every replica immediately.

For a planned zero-downtime change, create a second token with the same explicit scope instead:

1. create a new token;
2. store the new value in the host;
3. deploy or restart every replica;
4. verify requests and health with the new deployment;
5. revoke the old token.

farthershore backend tokens create my-business --format json --idempotency-key <persisted-backend-tokens-create-attempt-key>
# update FS_RUNTIME_TOKEN and redeploy
farthershore backend tokens revoke my-business <old-token-id> --yes

Deleting a backend also revokes runtime tokens bound to that backend.

Token kinds#

If --kind is omitted, an environment-scoped token defaults to test and an unscoped token defaults to live. Pass --kind live or --kind test only when you intentionally need to override that default. The kind is part of the token's runtime classification; it does not broaden its business, environment, backend, meter, or route scope. Rotation preserves the stored kind exactly, including an explicit override.

Recovery checklist#

If bootstrap or verification fails:

1. confirm the process has a nonempty FS_RUNTIME_TOKEN;
2. list token metadata and check that it is active;
3. check that its scope includes the selected environment/backend;
4. check gateway_verification, plus tunnel when applicable;
5. redeploy after any host secret change;
6. inspect backend status and application verification diagnostics without logging the token itself.