Skip to content

Authentication#

Authentication is required for the majority of the Buf CLI commands that interact with the Buf Schema Registry (BSR). There are two main ways to authenticate:

  1. Use buf registry login. We recommend this for local development authentication.
  2. Populate a BUF_TOKEN environment variable. We recommend this for CI systems.

In either case, you're using an authentication token generated by the BSR.

You don't need credentials to view public modules in the public BSR. You can give it a try here: https://buf.build/connectrpc/eliza/sdks/main

Authenticating locally#

Log in#

To authenticate with the CLI:

  1. Log in to the BSR from the command line:

    $ buf registry login

    If you're on a private BSR instance, specify it in the command:

    $ buf registry login buf.build

  2. Your browser opens. Log into the BSR and click Approve to approve the CLI access.

Log out#

To log out, run

$ buf registry logout

Tokens#

Create an API token#

  1. Go to your account settings.
  2. Click the Create New Token button, select an expiration time, and add a note for yourself to distinguish this token from others.
  3. Click Create and copy the token to your clipboard.

This token identifies you to the BSR and must be kept secret.

Revoke an API token#

An API token can be revoked from the same user settings page. Simply find the name of the token in the list and delete it. It immediately ceases to be a valid authentication method.

Bot users for Pro and Enterprise#

Pro and Enterprise users can create bot users and associated tokens. Bot users are headless users created and managed by the BSR instance administrators.

  1. Go to the admin panel for your private BSR instance and select Bot Users in the left side menu. For example, if your server is https://buf.example.com, then it's available at https://buf.example.com/admin/bot-users.
  2. Click the Create bot user button, then input a username to create the bot user.
  3. After the user is created, click on its name to go to the user details page and manage its tokens there.

Authenticating in CI#

If you wish to add authentication to your continuous integration jobs, we recommend storing the token in your provider's secret storage.

Access the secret token as specified by your CI provider and make it available as a BUF_TOKEN environment variable .

If this isn't possible, you can also login via the Buf CLI (assuming BUF_TOKEN is set):

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

For GitHub Actions, follow these steps:

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

You can now use any of the authenticated Buf CLI commands, such as buf push.

Advanced#

Where BSR credentials are stored locally#

Credentials are stored in $HOME/.netrc. After running buf registry logout, all existing BSR credentials are removed from $HOME/.netrc. If you're developing on a Windows machine, the credentials file is %HOME%/_netrc.

For more information on .netrc, check out the curl documentation.

BUF_TOKEN formats#

BUF_TOKEN is an environment variable that holds the API token used for authentication. It can contain either a single or multiple tokens.

Single token#

BUF_TOKEN can contain a single token that's used when authenticating with the BSR. You can set BUF_TOKEN by running this command:

$ export BUF_TOKEN=${YOUR_TOKEN}

Multiple tokens#

The BUF_TOKEN environment variable can also contain tokens with specific BSR addresses. Each token has the format ${BUF_TOKEN}@${BSR_HOSTNAME} with multiple tokens separated by a comma. The Buf CLI finds the correct authentication token for each remote address. You can set BUF_TOKEN by running the following command:

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

Order of precedence#

The order of precedence for CLI authentication is:

  1. The BUF_TOKEN environment variable is used if it's set.
  2. The .netrc file.

IP address blocking#

We block access to all BSR instances from any IP address that Google classifies as being located in a country sanctioned by the US OFAC. Trying to access the BSR from these IP addresses results in a 403: Forbidden error.

If you believe your IP addresses are being categorized erroneously, you can report the issue directly to Google.