Heroku API Getting Started: Quick Guide & First Request (2026)

Getting started overview

To begin interacting with the Heroku API, developers typically follow a structured process that includes account registration, API key acquisition, and initial authentication. The Heroku API enables programmatic control over various aspects of the Heroku platform, such as application deployment, resource scaling, and add-on management. This guide outlines the essential steps to get an environment configured and execute a first successful API call.

Heroku supports several programming languages and offers a command-line interface (CLI) that simplifies many common operations. While the CLI can perform many tasks, direct API interaction provides granular control for custom integrations and automation workflows.

Quick Reference Steps

The following table provides a high-level overview of the initial steps to get started with the Heroku API:

Create an account and get keys

Accessing the Heroku API requires an active Heroku account. If you do not already have one, you can register for an account through the official Heroku website. Heroku provides various pricing tiers, starting with Eco Dynos at $5/month. While there is no longer a completely free tier for dynos, initial account creation allows access to other Heroku features and management of billing. Review the Heroku pricing details for current offerings.

1. Sign Up for a Heroku Account

1. Navigate to the Heroku signup page.
2. Fill out the required information, including your name, email address, company (optional), role, and preferred programming language.
3. Accept the terms of service and complete the registration process.

2. Install the Heroku CLI

The Heroku Command Line Interface (CLI) is the recommended tool for interacting with the Heroku platform, including managing API keys. Installing the CLI will also facilitate authentication and provide a way to retrieve your API token.

1. Follow the instructions on the Heroku CLI installation guide specific to your operating system (macOS, Windows, or Ubuntu).
2. After installation, open your terminal or command prompt and verify the installation by running: heroku --version

3. Log In to the Heroku CLI

Once the CLI is installed, you need to log in to authenticate your session. This process typically opens a browser window for a secure login.

heroku login

Follow the prompts in your browser to complete the login. Upon successful login, your terminal will confirm that you are logged in as your Heroku account.

4. Retrieve Your Heroku API Key (Auth Token)

The Heroku API uses token-based authentication, specifically OAuth 2.0 bearer tokens. Your personal API key (also referred to as an auth token or access token) is required for making direct API requests. This token can be found and regenerated in your Heroku Dashboard.

1. Log in to your Heroku Dashboard.
2. Navigate to your Account settings.
3. Scroll down to the API Key section.
4. Click Reveal to view your API key. Copy this key, as it will be used as the Authorization header in your API requests.

It is crucial to treat your API key like a password, as it grants full access to your Heroku account resources. Do not embed it directly in client-side code or commit it to public repositories. For server-side applications, use environment variables or a secure secret management system. For information on OAuth 2.0 best practices, refer to the OAuth 2.0 specification.

Your first request

With an account created, the Heroku CLI installed and logged in, and your API key retrieved, you can now make your first authenticated request to the Heroku API. A common first request is to list your existing applications.

API Endpoint Details

• Base URL: https://api.heroku.com
• Endpoint: /apps
• Method: GET
• Headers Required:
  • Accept: application/vnd.heroku+json; version=3
  • Authorization: Bearer YOUR_API_KEY

Example using curl

Use the curl command-line tool to make a GET request to the /apps endpoint. Replace YOUR_API_KEY with the actual API key you retrieved from your Heroku dashboard.

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

Expected Response

A successful response for an account with no applications will be an empty JSON array:

[]

If you have existing applications, the response will be a JSON array containing objects, with each object representing an application and its properties. For example:

[
  {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "my-example-app",
    "owner": {
      "email": "[email protected]",
      "id": "fedcba98-7654-3210-fedc-ba9876543210"
    },
    "region": {
      "id": "a10f7e41-115f-4d1e-8ad4-b04ad14015f6",
      "name": "us"
    },
    "stack": {
      "id": "543210ab-cdef-0123-4567-89abcdef0123",
      "name": "heroku-22"
    },
    "created_at": "2023-01-01T12:00:00Z",
    "updated_at": "2023-01-01T12:00:00Z",
    "web_url": "https://my-example-app.herokuapp.com/"
  }
]

This successful response indicates that your API key is valid and your environment is correctly configured to interact with the Heroku API.

Common next steps

After successfully making your first API call, you can explore more advanced interactions and integrate the Heroku API into your development workflows:

• Create an Application: Use the POST /apps endpoint to programmatically create new Heroku applications. You can specify parameters such as the application name, region, and stack.
• Manage Dynos: Scale your application's dynos using endpoints like PATCH /apps/{app_id_or_name}/formation to adjust the number and type of dynos.
• Configure Environment Variables: Set and retrieve configuration variables (config vars) for your applications using the GET /apps/{app_id_or_name}/config-vars and PATCH /apps/{app_id_or_name}/config-vars endpoints.
• Add-on Management: Integrate and manage Heroku Add-ons, such as Heroku Postgres or Heroku Redis, through the API to enhance your application's functionality.
• Webhooks: Set up webhooks to receive notifications for events happening within your Heroku applications, enabling real-time integrations and automation.
• Explore the API Reference: Consult the Heroku Platform API Reference for a comprehensive list of all available endpoints, request parameters, and response structures.
• Use SDKs: While Heroku doesn't provide official client SDKs beyond the CLI, many community-maintained libraries exist for popular languages. Alternatively, use generic HTTP clients in your preferred language to construct requests.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some typical problems and their solutions:

• 401 Unauthorized: Invalid API Key
  • Issue: This error indicates that the API key provided is either incorrect, expired, or missing.
  • Solution: Double-check that you have copied the correct API key from your Heroku dashboard. Ensure there are no leading or trailing spaces. If unsure, regenerate the API key in your account settings and try again.
• 403 Forbidden: Insufficient Permissions
  • Issue: Your API key might not have the necessary permissions for the requested action.
  • Solution: For a personal API key, this is less common for basic GET requests on your own apps. However, if you are using an API key from a team or an OAuth client, verify that the associated user or client has the required scope or access to the resources.
• 406 Not Acceptable: Invalid Accept Header
  • Issue: The Accept header is not correctly specified. The Heroku API requires a specific version format.
  • Solution: Ensure your Accept header is exactly Accept: application/vnd.heroku+json; version=3. Any deviation can lead to this error.
• Network Issues / Connection Refused
  • Issue: Your client cannot reach the Heroku API server.
  • Solution: Check your internet connection. Ensure no firewalls or proxies are blocking outgoing HTTPS requests to api.heroku.com.
• CORS Errors (for browser-based requests)
  • Issue: If you are attempting to call the Heroku API directly from a web browser (client-side JavaScript), you might encounter Cross-Origin Resource Sharing (CORS) errors.
  • Solution: The Heroku API is primarily designed for server-to-server interaction. Direct client-side calls are generally not supported due to security implications and CORS policies. It's recommended to route API calls through a backend server that acts as a proxy.

For further debugging, examine the exact error message and HTTP status code returned by the API. The Heroku Platform API Reference documentation provides detailed error codes and explanations for each endpoint.