How-to guides

Manage tokens

Create, scope, and revoke Personal and Service Access Tokens, and keep CI credentials short-lived with Trusted Builders.

Every request to a firewall carries an access token. This page covers creating them with the right scope, and revoking them. For which token type to use where, see Access tokens; for how token scope interacts with team permissions, see Access and permissions.

Create a token

  1. In the dashboard, open the user menu in the lower-left corner and select Access tokens (it is not in the main sidebar), then choose Create token.
  2. Name it after what will use it: your machine for a PAT, the system for a SAT (ci-pipeline, build-server-eu).
  3. Pick a validity. Dashboard presets range from 1 day to 1 year, defaulting to 7 days. The API accepts any duration up to 2 years (validForHours).
  4. Optionally narrow the scope (next section).
  5. Copy the value. It is shown once.

Creating a PAT requires the ns:create:pat permission (every user has it through the everybody team); creating a SAT requires ns:create:service-token (admins by default).

Scope a token

Two optional restrictions make a leaked token less useful:

  • Permissions. A token can carry a subset of permissions. A PAT with only fw:access works for installs but cannot read or change configuration, even if you can. A token can never do more than its creator: PATs are capped by your team permissions, and SATs by what the creating session holds.
  • Restrict to firewalls. A token listing specific firewalls is rejected on every other firewall.

A CI token for one project is the canonical case: a SAT with fw:access only, restricted to that project's firewall.

Service Access Tokens are further capped by a fixed catalog: they can hold access, read, and configuration/rule/exception update permissions, but never team management, credential updates, or namespace and firewall deletion. See Permissions.

Revoke a token

Delete the token from the Access tokens page. Validation fails from that moment; there is no grace period. Expired tokens reject the same way, so an expiry is the automatic version of this.

Any system still using a deleted token starts failing on its next request, which is the point during an incident and a hazard during housekeeping. Rotate by creating the replacement first, updating the consumer, then deleting the old token.

Tokens for CI/CD

A SAT stored in CI is a long-lived secret. On GitHub Actions, register a Trusted Builder instead: each run exchanges its OpenID Connect identity for a Service Access Token valid for 15 minutes, so there is nothing to rotate. Set up CI/CD pipelines covers both, per CI system, and how to tag each run's requests with its run ID.

Verify

Use the new token once, then check it appears in the logs attributed as expected:

bsfw logs --firewall <firewall-id>

PAT requests are attributed to the owning user; SAT requests to the token's name.

Manage exceptions

Create scoped, documented, expiring waivers when a rule blocks a package you need.

Manage upstream credentials

Set and rotate the credentials a firewall uses against private upstreams, or supply them just-in-time per request.

On this page

Create a tokenScope a tokenRevoke a tokenTokens for CI/CDVerifyRelated