Skip to main content

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#

The order of precedence for CLI authentication is:

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

BUF_TOKEN#

An environment variable that holds the API token, used for authentication.

netrc file#

The buf CLI reads its authentication credentials from your .netrc file. There is a buf command that manages the .netrc file for you, run this command:

$ buf registry login

You'll be prompted for your username, as well as the token and you'll end up with this:

~/.netrc
machine buf.build    login <USERNAME>    password <TOKEN>

You can logout at any time with this command:

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

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.