Last updated July 02, 2026

Authentication on Heroku uses one of these methods, depending on the situation:

• Web-based authentication
• Email and password
• API token
• SSH key

The heroku command uses the email address and password to obtain an API token. All other Heroku API requests use this token for authentication. A user can regenerate the token at will in the Heroku 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.

Heroku uses the SSH key 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 your machine’s system keychain by default. If a supported keychain is unavailable, the Heroku CLI stores API tokens in the standard Unix file ~/.netrc ($HOME\_netrc on Windows).

The CLI supports Keychain Access on macOS, Secret Service on GNOME-based Linux distributions, and Windows Credential Manager. Our credential manager tool automatically determines which supported keychains are available and stores your credentials in secure, OS-native storage. If a supported keychain isn’t available, the credential manager falls back to storing your tokens in your .netrc file.

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 uses the API key stored in .netrc to authenticate with the Heroku HTTP Git service.

To continue to store your token in .netrc, you can set the HEROKU_NETRC_WRITE environment variable to true to override the use of the system keychain by default.

If you set HEROKU_NETRC_WRITE=true and then unset it to enable the credential manager to use your system keychain or if you never set the environment variable, your credentials remain in your .netrc file. The credential manager doesn’t automatically remove them, though your token expires after the designated time period. You can remove your credentials by running HEROKU_NETRC_WRITE=true heroku logout or manually editing the .netrc file to remove credentials that you don’t need.

Usage Examples

System Keychain

Running heroku login or any other heroku command that requires authentication saves or updates your token in your system keychain. After logging in, you can verify that the CLI stored your token correctly by opening your keychain app and searching for the heroku-cli entry.

Netrc

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

Git Credential Helper

The CLI automatically configures a Git credential helper anytime you:

• Log in with heroku login
• Create a Heroku app with heroku create
• Set or update the Git remote on an existing app repository with heroku git:remote

This credential helper automatically retrieves your Heroku token from your system keychain or, if a supported keychain isn’t available, from your .netrc file.

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 an OAuth token. Using the account’s password is invalid and doesn’t work.