Buf Docs

Appearance

Authentication ​

Authenticating to the Buf Schema Registry (BSR) unlocks private modules, buf push, and any admin action scoped to your user, organization, or instance. Public modules stay readable without credentials: buf.build/connectrpc/eliza/sdks/main is browsable as is.

The BSR identifies the Buf CLI by an API token. You can create one manually in your account settings and export it as BUF_TOKEN, or run buf registry login to approve the CLI in a browser and have it cache a token on disk.

If you don’t have the Buf CLI yet, see Install the Buf CLI.

Log in from the CLI ​

Run buf registry login and approve the session in your browser:

sh
buf registry login

For a private BSR instance, pass the hostname:

sh
buf registry login buf.example.com

The CLI opens your browser, you sign in, click Approve, and the CLI writes the resulting token to $HOME/.netrc (%HOME%/_netrc on Windows).

To log out:

sh
buf registry logout

buf registry logout removes every BSR credential from .netrc. See the buf registry logout reference for details.

Authenticate in CI ​

For CI, store your token in the provider’s secret store and expose it to the job as BUF_TOKEN. The Buf CLI reads that environment variable on every command, so authenticated operations like buf push work without additional setup.

Provider docs for secret storage:

GitHub Actions ​

  1. In your repository, go to Settings > Secrets and variables > Actions.
  2. Click New repository secret.
  3. Name the secret BUF_TOKEN and paste the token as the value.
  4. Click Add secret.

Reference BUF_TOKEN in your workflow environment, and any authenticated Buf CLI command works from there.

Writing a .netrc for other tools ​

If something else in the job reads credentials from .netrc rather than the environment, pipe BUF_TOKEN into buf registry login:

sh
echo "${BUF_TOKEN}" | buf registry login --token-stdin

This writes the same .netrc entry an interactive buf registry login produces.

Create and revoke API tokens ​

Create a token ​

  1. Go to your account settings.
  2. Click Create New Token, pick an expiration, and add a note that distinguishes this token from the others on the list.
  3. Click Create and copy the token to your clipboard.

Treat the token as a secret. It identifies you to the BSR for every operation, including writes.

Revoke a token ​

Find the token by name on the same account settings page and delete it. Revocation takes effect immediately.

Bot users ​

Bot users are a private-instance feature. They aren’t offered on the public buf.build BSR.

Instance administrators can create bot users for headless automation, producing tokens that aren’t tied to an individual account and so survive staff changes.

  1. Open your instance’s admin panel and select Bot Users from the left side menu. For https://buf.example.com, that’s https://buf.example.com/admin/bot-users.
  2. Click Create bot user and enter a username.
  3. Click the new user’s name to open its detail page, then create and manage tokens from there.

BUF_TOKEN reference ​

BUF_TOKEN holds the API token the Buf CLI uses to authenticate to the BSR. It accepts a single token, or a comma-separated list keyed by hostname when you work against more than one BSR.

Single token ​

Used against every BSR the CLI contacts:

sh
export BUF_TOKEN=${YOUR_TOKEN}

Multiple tokens for multiple BSR instances ​

If you hit both the public buf.build and a private instance from the same machine or CI job, give each token an @hostname suffix and separate the entries with commas:

sh
export BUF_TOKEN=${TOKEN1}@${BSR_HOSTNAME1},${TOKEN2}@${BSR_HOSTNAME2}

The Buf CLI matches the remote’s hostname to the right token for each request.

Precedence and storage ​

The CLI resolves credentials in this order:

  1. BUF_TOKEN, if set.
  2. $HOME/.netrc (%HOME%/_netrc on Windows).

buf registry login writes to .netrc; buf registry logout clears every BSR entry from it. For the file format, see the curl documentation.

Blocked regions ​

Buf blocks access to all BSR instances from IP addresses that Google classifies as located in countries sanctioned by the US OFAC. Requests from blocked IPs return 403: Forbidden.

If you think your IP is miscategorized, report it to Google.