Heroku API Authentication: Methods & Security Best Practices (2026)

Authentication overview

The Heroku API provides programmatic access to manage applications, add-ons, and other resources on the Heroku platform. Authentication is a critical component for securing these interactions, ensuring that only authorized users and applications can perform actions. The Heroku API primarily supports two robust methods for authentication: OAuth 2.0 and API tokens (also known as Heroku API Keys). Choosing the appropriate method depends on the use case, whether it involves user-delegated access for third-party applications or direct programmatic access for scripts and automation.

OAuth 2.0 is an industry-standard protocol for authorization that allows a third-party application to obtain limited access to a user's resources without exposing the user's credentials. This is particularly useful for applications that need to interact with Heroku on behalf of a user, such as deployment tools or monitoring services. The protocol defines various grant types to accommodate different application architectures and user interaction flows. For instance, the authorization code grant type is commonly used for web applications, while the client credentials grant type can be suitable for server-to-server interactions where no user is involved.

API tokens, on the other hand, are long-lived, secret keys that grant direct access to the Heroku API. These tokens are suitable for scripts, command-line tools, and continuous integration/continuous deployment (CI/CD) pipelines where user interaction is not feasible or desired. They provide a straightforward way to authenticate automated processes but require careful management to prevent unauthorized access. Heroku's documentation provides comprehensive details on how to manage these tokens securely, including recommendations for rotation and storage practices.

All authenticated requests to the Heroku API must be made over HTTPS to ensure that credentials and data are encrypted in transit. This adherence to secure communication protocols is a fundamental security practice, protecting against eavesdropping and man-in-the-middle attacks. Heroku's platform API reference details the specific endpoints and expected authentication headers for various operations, guiding developers in constructing secure API calls.

Supported authentication methods

Heroku API supports the following primary authentication methods:

Getting your credentials

OAuth 2.0 credentials

To use OAuth 2.0 for authentication with the Heroku API, you must first register your application with Heroku. This process involves obtaining a Client ID and Client Secret, which uniquely identify your application to the Heroku platform. These credentials are vital for initiating the OAuth flow and exchanging authorization codes for access tokens.

1. Register your application: Navigate to your Heroku Dashboard, go to 'Account settings', and then 'Applications'. Click 'Register new application'. You will need to provide an application name, a description, and crucially, one or more Redirect URIs. The Redirect URI is where Heroku will send the user back after they authorize your application, along with an authorization code.
2. Obtain Client ID and Client Secret: After registration, Heroku will provide you with a Client ID and Client Secret. The Client ID is public, but the Client Secret must be kept confidential, as it is used to authenticate your application to Heroku's authorization server.
3. Initiate the authorization flow: Your application will redirect the user to Heroku's authorization endpoint, including your Client ID, desired scopes (permissions), and the Redirect URI.
4. User grants access: The user logs into Heroku (if not already logged in) and is prompted to authorize your application to access their Heroku resources with the specified scopes.
5. Receive authorization code: If the user grants access, Heroku redirects them back to your specified Redirect URI with an authorization code.
6. Exchange code for access token: Your application then makes a server-side request to Heroku's token endpoint, exchanging the authorization code, Client ID, and Client Secret for an access token and optionally a refresh token. The access token is used to make authenticated API requests, while the refresh token can be used to obtain new access tokens once the current one expires, without requiring the user to re-authorize. For detailed steps, refer to the Heroku OAuth documentation.

API Tokens (Heroku API Key)

Heroku API tokens provide a simpler, direct method for authentication, ideal for scripts and automated processes. These tokens are generated through the Heroku CLI or your account settings.

1. Using the Heroku CLI: The most common way to obtain an API token is by logging in via the Heroku CLI. After installing the Heroku CLI, open your terminal and run heroku login. This command will open a web browser for you to log in to your Heroku account. Once logged in, your API token is stored securely for CLI operations. To retrieve it explicitly, you can run heroku auth:token. This command outputs your current API token, which can then be used in scripts or environment variables.
2. From Heroku Dashboard: You can also find your API token in your Heroku account settings. Navigate to the Heroku Dashboard, click on your account icon in the top right, select 'Account settings', and scroll down to the 'API Key' section. You can reveal your API key there. It is crucial to treat this key as sensitive as a password.

Authenticated request example

Once you have an access token (from OAuth 2.0) or an API token (Heroku API Key), you can use it to make authenticated requests to the Heroku API. The token should be included in the Authorization header of your HTTP requests, typically using the Bearer scheme for OAuth tokens or directly as a key for API tokens.

Using an OAuth 2.0 access token

For requests authenticated with an OAuth 2.0 access token, the Authorization header should be formatted as Bearer YOUR_ACCESS_TOKEN.

curl -X GET \ 
  https://api.heroku.com/apps \ 
  -H "Accept: application/vnd.heroku+json; version=3" \ 
  -H "Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN"

Using an API Token (Heroku API Key)

For requests authenticated with a Heroku API Key, the Authorization header should be formatted as Bearer YOUR_HEROKU_API_KEY. While the term 'API Key' is used, Heroku's implementation uses the Bearer token scheme for these as well.

curl -X GET \ 
  https://api.heroku.com/apps \ 
  -H "Accept: application/vnd.heroku+json; version=3" \ 
  -H "Authorization: Bearer YOUR_HEROKU_API_KEY"

In both examples, YOUR_OAUTH_ACCESS_TOKEN or YOUR_HEROKU_API_KEY should be replaced with your actual token. The Accept header specifies the API version and format, which is a standard practice for Heroku API requests.

Security best practices

Adhering to security best practices is crucial when handling Heroku API credentials to prevent unauthorized access and protect your applications and data.

• Keep credentials confidential: Treat your Client Secrets, API tokens, and refresh tokens with the same level of security as passwords. Never embed them directly in client-side code, public repositories, or commit them to version control systems like Git. Instead, use environment variables, secret management services, or secure configuration files.
• Use HTTPS exclusively: Always ensure that all communication with the Heroku API occurs over HTTPS. Heroku enforces HTTPS for all API endpoints, but it's a good practice to verify this in your client-side implementations. This encrypts data in transit, protecting against interception.
• Implement OAuth 2.0 securely: When using OAuth 2.0, follow the recommended grant types for your application type. For web applications, the authorization code grant flow with PKCE (Proof Key for Code Exchange) is highly recommended for enhanced security, as detailed in the RFC 7636 PKCE specification. Always validate the state parameter to prevent Cross-Site Request Forgery (CSRF) attacks.
• Scope permissions narrowly: When requesting OAuth scopes or generating API tokens, always request or grant only the minimum necessary permissions required for your application or script to function. This principle of least privilege limits the potential damage if a token is compromised. For instance, if an application only needs to read application information, do not grant write or delete permissions.
• Rotate API tokens regularly: For API tokens used in automated systems, establish a regular rotation schedule. Periodically generate new tokens and revoke old ones. This minimizes the window of vulnerability if a token is inadvertently exposed.
• Monitor API usage: Keep an eye on your Heroku activity logs and API usage metrics. Unusual patterns or spikes in API calls could indicate unauthorized access or a compromised token. Heroku provides various logging and monitoring tools that can be integrated with external services.
• Secure storage for refresh tokens: If your application uses OAuth 2.0 refresh tokens, store them securely. They are long-lived and can be used to obtain new access tokens without user interaction. Encrypt them at rest and restrict access to them.
• Avoid hardcoding tokens: Never hardcode API tokens or client secrets directly into your application code. Use environment variables (e.g., HEROKU_API_KEY), a dedicated secrets management service, or a configuration system that loads secrets dynamically at runtime.
• Revoke compromised tokens immediately: If you suspect an API token or OAuth access token has been compromised, revoke it immediately through your Heroku Dashboard or via the Heroku API itself. This action invalidates the token, preventing further unauthorized use.