Authentication

Authentication is required for the majority of the buf CLI commands that interact with the BSR.

Create an API token

Sign up or log in at https://buf.build/login and navigate to your account settings at https://buf.build/settings or by selecting "Settings" from the avatar dropdown at the top-right corner of the page.

On the settings page, click the Create New Token button, select an expiration time, and add a note for yourself to distinguish this token from others. Click Create and copy the token to your clipboard.

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

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

Authenticating the CLI

netrc file

Using a .netrc file is the recommended way to authenticate using the buf cli. To authenticate with a .netrc file, run

$ buf registry login

The buf registry login command will prompt you for a username and token, with the resulting .netrc file as:

machine buf.build
    login <USERNAME>
    password <TOKEN>

To log out, run

$ buf registry logout

After running buf registry logout, all existing BSR credentials removed from $HOME/.netrc.

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

If you're developing on a Windows machine, the credentials file is %HOME%/_netrc.

BUF_TOKEN

BUF_TOKEN is an environment variable that holds the API token, used for authentication. There are two formats for the BUF_TOKEN:

Single Token

BUF_TOKEN can contain a single token. This token is used when authenticating with the BSR. You can set BUF_TOKEN by:

$ export BUF_TOKEN=${YOUR_TOKEN}

Multiple BSR Remote Tokens

The BUF_TOKEN environment variable can also contain tokens with specific BSR addresses. Each token has the format ${BUF_TOKEN}@${REMOTE_ADDRESS} with multiple tokens separated by ,. The buf CLI will find the correct authentication token for different remote addresses. You can set BUF_TOKEN by:

$ export BUF_TOKEN=${TOKEN1}@{REMOTE1},${TOKEN2}@{REMOTE2},...

Order of precedence

The order of precedence for CLI authentication is:

1. The BUF_TOKEN environment variable is used if it's set. This is recommended for CI systems.
2. The .netrc file. This is recommended for development authentication.

CI authentication

If you wish to add authentication to your continuous integration jobs, we recommend storing the token in your providers secret storage, if possible. Such as: GitHub Actions , Travis CI , CircleCI.

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

If this is not possible, you can also login via the CLI (assuming BUF_API_TOKEN and BUF_USER are set):

$ echo ${BUF_API_TOKEN} | buf registry login --username ${BUF_USER} --token-stdin

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

Note that we have official GitHub Actions that enable you to quickly configure authentication for CI jobs.