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 firewall 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.

Credentials for an artifact host

Some registries serve package files from a different host than their metadata. Credentials set on the upstream are only sent to the upstream's own host, so each artifact host that needs authentication requires its own entry. Composer is the current case: most Packagist dist URLs use api.github.com, while other packages can name another host. See Artifact host credentials.

For api.github.com, set the GitHub token on the upstream's edit form, or through the API:

curl -X PUT \
  -H "Authorization: Bearer $BYTESAFE_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"token\": \"$NEW_ARTIFACT_TOKEN\"}" \
  "https://eu-sov-1.bytesafecloud.eu/v1/<namespace-id>/config/<firewall-id>/upstreams/<upstream-id>/artifact-credentials/api.github.com"

It needs the same fw:update:credentials permission, is encrypted at rest the same way, and merges per field, so rotating one field leaves the others alone.

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 show up as an authentication error on the client. That follows from how resolution works: the firewall asks each of its upstreams in turn, and one upstream rejecting it must not break a request that another upstream can answer, so it skips that upstream and serves what the others return.

If the private registry is the only upstream holding the package, nothing is left to serve and the install fails, with an error that names the package rather than the credential. See Failure behavior for how that failure reaches each client.

If private packages disappear after a rotation, check the credential first.

The firewall records the rejection in its log as an upstream error, naming the upstream and the status it returned. That is the quickest way to confirm it: run bsfw logs --all-users --kind error --since 24h, or set Status to Error on the dashboard's Logs page. See Check for failing upstreams.

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.

How-to: Configure upstreams, Review the audit log
Reference: Upstreams, Tokens, CLI
Concept: Upstreams and caching