Manage Gateway Tokens

Each Gateway authenticates to the Firezone control plane with its own single-owner token: a token bound to exactly one Gateway. This guide covers generating, rotating, and revoking Gateway tokens, and upgrading Gateways that still connect with a legacy multi-owner token. For how tokens identify Gateways, see Gateway tokens.

Generate a token for a new Gateway

1. In the admin portal, open Sites → <your Site> and click Deploy a gateway.
2. The portal creates the Gateway and shows its token in the install instructions for each install method.
3. Save the token to a secure location; it won't be shown again.

The first Gateway process to connect with the token claims it. While that Gateway is connected, connection attempts from other processes using the same token are rejected, so deploy each token to exactly one host. To deploy more Gateways, repeat this flow once per Gateway.

The Terraform modules accept a list of single-owner tokens and deploy one Gateway instance per token, so mint one token per instance you plan to deploy.

Rotate a Gateway's token

1. In the admin portal, open Sites → <your Site> and expand the Gateway in the Gateways tab.
2. Click Rotate token and confirm. The new token is shown only once, so save it now.
3. Update the Gateway's configuration (e.g. its FIREZONE_TOKEN environment variable or token file) with the new token and restart the Gateway.

Rotation doesn't interrupt the running Gateway: the current token keeps working until the Gateway first connects with the new token or 4 hours pass, whichever comes first. A token the Gateway has never connected with is replaced immediately instead. Rotating again before the Gateway picks up the replacement replaces only the pending token; the token in use and its deadline are untouched.

Upgrade a Gateway from a legacy token

Gateways deployed before single-owner tokens connect with a legacy multi-owner token shared by every Gateway in the Site. These Gateways show a legacy token badge in the Gateways tab. To upgrade one:

1. In the admin portal, open Sites → <your Site> and expand the Gateway in the Gateways tab.
2. Click Upgrade token and confirm. This issues a single-owner token that only this Gateway can use.
3. Update the Gateway's configuration with the new token and restart it. The upgrade completes when the Gateway reconnects with its own token.
4. Repeat for each Gateway in the Site, then revoke the legacy token (below).

The legacy multi-owner token keeps working until you revoke it, so Gateways you haven't upgraded yet stay connected.

Revoke legacy tokens

1. In the admin portal, open Sites → <your Site> and select the Legacy tokens tab. Each remaining multi-owner token is listed along with the number of Gateways currently connected with it.
2. Revoke the token once no Gateways are using it, or immediately if you intend to disconnect them.

Revoking a token disconnects any Gateways still connected with it.

Manage tokens with the REST API

Single-owner tokens can be managed programmatically with the REST API:

• POST /sites/{site_id}/gateways/{gateway_id}/token creates a single-owner token for a Gateway. At most one active token can exist per Gateway; if one already exists this returns 409 Conflict; rotate or delete it instead.
• POST /sites/{site_id}/gateways/{gateway_id}/token/rotate rotates a Gateway's token with the same grace-period behavior as the portal.
• DELETE /sites/{site_id}/gateway_tokens/{id} deletes a token.

Need help? See all support options.