Heroku CLI Authentication
Last updated March 13, 2023
Table of Contents
Authentication to Heroku uses one of the following mechanisms, depending on the situation:
- Web-based authentication
- Email and password
- API token
- SSH key
The email address and password are used by the heroku
command
to obtain an API token. This token is used for authentication in
all other Heroku API requests, and can be regenerated at will
by the user in the heroku.com web interface. Regenerating an
API token invalidates the current token and creates a new one.
If a user changes their password, their API token regenerates.
The SSH key is used for git push authentication when using SSH Git transport. You can use heroku keys
to manage your SSH keys on Heroku.
API token storage
The Heroku command-line tool stores API tokens in the standard
Unix file ~/.netrc
($HOME\_netrc
on Windows).
The netrc format is well-established and well-supported by
various network tools on unix. With Heroku credentials stored in
this file, other tools such as curl -n
can access the Heroku API
with little or no extra work. When using the default HTTP transport, Git uses cURL, and cURL will use the API key stored in .netrc
to authenticate with the Heroku HTTP Git service.
Setting the HEROKU_API_KEY
environment variable on your machine will override any token set in the netrc file.
Usage examples
Running heroku login
(or any other heroku
command that
requires authentication) creates or updates your ~/.netrc
file:
$ heroku login
heroku: Press any key to open up the browser to login or q to exit
› Warning: If browser does not open, visit
› https://cli-auth.heroku.com/auth/browser/***
heroku: Waiting for login...
Logging in... done
Logged in as me@example.com
$ cat ~/.netrc
machine api.heroku.com
login me@example.com
password c4cd94da15ea0544802c2cfd5ec4ead324327430
machine git.heroku.com
login me@example.com
password c4cd94da15ea0544802c2cfd5ec4ead324327430
Retrieving the API token
You can display the token via the CLI:
$ heroku auth:token
c4cd94da15ea0544802c2cfd5ec4ead324327430
Netrc file format
The file contains a list of free-form records and comments. Comments
start with a #
(hash) symbol and continue to the end of the line.
Each record is of the form:
machine api.heroku.com
login me@example.com
password ABC123
The password field is actually an oauth token. Using the account’s password is invalid and will not work here.