Manage upstream credentials
Set and rotate the credentials a firewall uses against private upstreams, or supply them just-in-time per request.
Upstream credentials are what the firewall presents to a private registry when fetching packages or forwarding publishes. They are deliberately separated from the rest of the configuration: encrypted at rest, never returned by the API, excluded from exports, and changed through their own permission (fw:update:credentials) and audit event.
Which fields you set decides the auth style the firewall sends: a token goes out as an Authorization: Bearer header, a username and password as HTTP basic auth. If both are set, the token wins. Details per path in the upstreams reference.
Set or rotate credentials
With the CLI, set NEW_UPSTREAM_TOKEN from your secret manager or a secure prompt before running the command:
bsfw config credentials --firewall <firewall-id> --upstream <upstream-id> --token "$NEW_UPSTREAM_TOKEN"Use the upstream's id from the firewall config, not its endpoint. Fields you do not pass stay unchanged, so rotating a token does not require re-entering a username and password. Alternatives: --user/--password flags, --stdin with a JSON body ({"token": "..."}), or an interactive prompt when run without flags in a terminal.
In the dashboard: open the firewall's Upstreams, edit the upstream, and replace the credential field. Existing values show as a placeholder meaning "keep the stored value"; leave it untouched to keep, overwrite to replace, clear it to remove.
Rotation involves the registry as well: create the new credential there first, set it on the firewall, then revoke the old one at the registry. In that order, no request is left holding a credential that no longer works.
Verify
Install a package that only the private upstream serves, then check that the log entry contains its upstream ID:
bsfw logs --firewall <firewall-id>A wrong credential does not produce an install error: the upstream is skipped and its packages appear missing. If private packages vanish after a rotation, suspect the credential first.
Every change is recorded in the audit log as firewall.credentials.upsert, with the actor and which fields changed, never the values.
Just-in-time credentials
Some organizations do not want upstream secrets stored server-side at all, even encrypted. For that case, a client can carry the upstream credentials inside its own token per request, using the credential envelope (env- token format): the firewall uses the bundled credentials for the named upstreams instead of stored ones, and discards them with the request.
The envelope format is documented in the tokens reference. Building the envelope is currently an integration task (base64-encoded JSON around an existing token); there is no dashboard flow for it.
Who can do this
fw:update:credentials is granted to the admin team and the firewall's owning team by default, and can be granted per firewall to other teams. Service Access Tokens can never hold it; credential changes always trace to a person. See Permissions.
Related
- How-to: Configure upstreams, Review the audit log
- Reference: Upstreams, Tokens, CLI
- Concept: Upstreams and caching
Manage tokens
Create, scope, and revoke Personal and Service Access Tokens, and keep CI credentials short-lived with Trusted Builders.
Migrate from previous-generation Bytesafe
Move from Bytesafe hosted registries, policies, and plugins to the Dependency Firewall, with private packages in a repository manager and policy as rules.