Access Tokens

Every request to a firewall is authenticated. Package managers, the CLI, and CI systems all present an access token. There are three kinds.

Exact lifetimes, permissions, and wire format are in the tokens reference.

Personal Access Tokens (PAT)

Use a PAT on your own machine. Installs are attributed to you in the firewall logs, which is what makes log entries useful when someone asks why a package was fetched.

Access Tokens is not in the main sidebar. Open the user menu in the lower-left corner of the dashboard (your name and avatar), then select Access Tokens.

On that page:

1. Select Create Token, fill in the name, validity, and permissions (see Permissions and validity below), and create it.
2. Copy the value straight away: it is shown once and cannot be retrieved afterwards. If you lose it, create a new token and revoke the old one.

Use it in your package manager config (see Ecosystems) or export it for the CLI:

export BYTESAFE_TOKEN=<your token>

Service Access Tokens (SAT)

Use a Service Access Token where no person is involved: CI pipelines, container builds, shared build servers. Service Access Tokens are created the same way from the Access Tokens page, given a name that identifies the system using it.

Do not reuse one Service Access Token everywhere. One token per system keeps the logs attributable, and it means revoking a leaked token affects that one system instead of every pipeline you run.

Permissions and validity

The Create Token dialog asks for a name, how long the token is valid, permissions, and optional firewall restrictions.

For PATs and SATs, leaving Restrict to firewalls empty allows every firewall the token has permission to use. Selecting firewalls limits the token to those firewall IDs.

SAT permissions are limited to unattended work. A SAT can install, publish, read firewall config, create or clone firewalls, and update config, rules, or exceptions when granted. It cannot manage upstream credentials, teams, tokens, namespace deletion, or firewall deletion.

Dashboard token presets are 1 day, 7 days, 30 days, 90 days, and 1 year. The API accepts validForHours; the default is 12 hours and the maximum is 2 years. Trusted Builder tokens are valid for 15 minutes.

Every token has an expiry, so pick a validity that matches how long the system will use it, and plan for the replacement. Trusted Builders avoid that work entirely, since each run gets its own token.

See Permissions for the permission catalog and Tokens for the wire format.

Trusted Builders (OIDC)

For CI systems that can prove their identity with OpenID Connect (OIDC), there is a better option than a stored secret: register the workflow as a Trusted Builder. At run time, the workflow exchanges its OIDC identity token for a short-lived Service Access Token. Nothing long-lived is stored in the CI system.

Trusted Builders currently support GitHub Actions. Setup is covered in the GitHub Actions guide.

Correlating requests with interaction IDs

A single token is often shared across many contexts: a build server runs every pipeline, a CI workflow runs every branch. Interaction IDs add traceability on top without minting a token per build, application, or team. Any token can carry an opaque interaction ID by appending it after a double colon:

<token>::build-4711

The firewall strips the suffix before validating the token and records it in the log entry. The value is opaque, so use whatever dimension you want to correlate on later: a CI run (build-4711), an application or project (checkout-service), an environment (staging), or a combination. The CLI does this with the --interaction flag or the BYTESAFE_INTERACTION environment variable.

Next steps

• Put the token to use: configure npm.
• See what your token is doing: view logs.