BytesafeDependency Firewall
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.

Prefer Trusted Builders over stored CI secrets

A SAT stored in CI is a long-lived secret. For CI systems that can prove their identity with OpenID Connect (currently GitHub Actions), register a Trusted Builder instead: each run exchanges its OIDC token for a Service Access Token valid for 15 minutes. There is nothing to rotate, and a token that leaks from a build log is worthless within the quarter hour.

Setup is covered in the GitHub Actions guide.

Keep logs attributable

  • One token per system. A shared ci token makes the firewall log useless for tracing which pipeline pulled a package.
  • Append an interaction ID (<token>::build-4711) to correlate all requests from one run. See Access Tokens.

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 tokenPrefer Trusted Builders over stored CI secretsKeep logs attributableVerifyRelated