Authentication is required for the majority of the Buf CLI commands that interact with the Buf Schema Registry (BSR). You can store authentication information locally in two ways:
- A
BUF_TOKEN
environment variable. We recommend this for CI systems. - The
.netrc
file. We recommend this for development authentication.
In either case, you're using an authentication token generated by the BSR. See create a token for generation instructions.
For more information on .netrc
, check out the curl documentation.
If you're developing on a Windows machine, the credentials file is
%HOME%/_netrc
.
Please note that buf registry login
only supports a single token; it does not support multiple BSR tokens in the way
that the BUF_TOKEN
environment variable does.
Order of precedence
The order of precedence for CLI authentication is:
- The
BUF_TOKEN
environment variable is used if it's set. - The
.netrc
file.
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. This token is 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}@${REMOTE_ADDRESS}
with multiple tokens separated by a comma. The Buf CLI will find the correct
authentication token for each remote address. You can set BUF_TOKEN
by running the following command:
$ export BUF_TOKEN=${TOKEN1}@{REMOTE1},${TOKEN2}@{REMOTE2},...
Manage tokens
Create an API token
- Sign up or log in at https://buf.build/login.
- Go to your account settings.
- 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.
Update an API token
To update the token in your .netrc
file:
- Create a new token in the BSR as shown above.
- Log in to the BSR and provide the new token. The new token value replaces the previous value in your
.netrc
file.
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.
Authenticate the Buf CLI
Log in and update .netrc
file
For local development, we recommend using a .netrc
file to authenticate when using the Buf CLI. To authenticate with a
.netrc
file:
-
Log in to the BSR from the command line
$ buf registry login
If you're on a private BSR instance, specify your domain in the command:
$ buf registry login <PRIVATE_BSR_SERVER>
-
The Buf CLI will prompt you for your BSR username and a token. Provide them, and the resulting
.netrc
file looks like this:~/.netrcmachine buf.build login <USERNAME> password <TOKEN> machine go.buf.build login <USERNAME> password <TOKEN>
Log out
To log out, run
$ buf registry logout
After running buf registry logout
, all existing BSR credentials are removed
from $HOME/.netrc
.
CI authentication
If you wish to add authentication to your continuous integration jobs, we recommend storing the token in your provider's secret storage, if possible. For example:
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 Buf 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 CLI commands, such as buf push
.
Note that we have official GitHub Actions that enable you to quickly configure authentication for CI jobs.