Authentication on Heroku uses one of three mechanisms, depending on the situation:
- 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.
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
$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 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.
HEROKU_API_KEY environment variable on your machine will interfere with normal functioning of auth commands from Toolbelt.
heroku login (or any other
heroku command that requires authentication) will create or update your
$ ls .netrc ls: .netrc: No such file or directory $ heroku login Enter your Heroku credentials. Email: email@example.com Password: $ cat .netrc machine api.heroku.com login firstname.lastname@example.org password c4cd94da15ea0544802c2cfd5ec4ead324327430 machine git.heroku.com login email@example.com password c4cd94da15ea0544802c2cfd5ec4ead324327430 $
Retrieving the API token
You can display the token via the CLI:
$ heroku auth:token c4cd94da15ea0544802c2cfd5ec4ead324327430
Authenticating with the API token
Having logged in, you can use
curl to access the Heroku API:
$ curl -H "Accept: application/json" -n https://api.heroku.com/apps
You can also create a file
~/.curlrc, containing extra command-line options for curl:
--netrc --header "Accept: application/json"
With this file, the command is simply:
$ curl https://api.heroku.com/apps
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 firstname.lastname@example.org password ABC123
One other type of record,
macdef, can appear in
.netrc files, but it is not commonly used and is ignored by the