Heroku Platform API Getting Started: Quickstart Guide (2026)

Getting started overview

This guide outlines the essential steps for developers to begin interacting with the Heroku Platform API. It covers account creation, obtaining necessary API credentials, and making a first successful API call. The Heroku Platform API enables programmatic control over various Heroku resources, including applications, add-ons, and dynos, facilitating automation and integration with custom workflows.

The API is a RESTful interface that uses standard HTTP methods and JSON for request and response bodies. Authentication primarily relies on OAuth 2.0 tokens, which can be obtained through the Heroku CLI or by creating specific API keys for programmatic access. Understanding the authentication mechanism is critical for making authenticated requests.

Before proceeding, ensure you have a Heroku account. While Heroku previously offered a free tier, Heroku's current pricing structure requires a paid plan to utilize dynos and other services. API access is implicitly granted to authenticated Heroku users, but direct costs apply to the resources managed via the API.

Create an account and get keys

To interact with the Heroku Platform API, you must first have an active Heroku account. If you do not already have one, navigate to the Heroku signup page and complete the registration process. Ensure you verify your email address to activate your account fully.

Installing the Heroku CLI

The Heroku Command Line Interface (CLI) is the recommended tool for managing Heroku applications and, crucially, for generating the API token required for Platform API access. Follow the Heroku CLI installation instructions relevant to your operating system. Once installed, open your terminal or command prompt.

Logging in to Heroku CLI

Before you can generate an API token, you need to log in to your Heroku account via the CLI. In your terminal, execute the following command:

heroku login

This command will open a web browser page where you can enter your Heroku credentials. After successful authentication, the browser will redirect you, and the CLI will confirm your login status. This step securely authenticates your local machine with your Heroku account.

Generating an API Token

With your CLI session authenticated, you can now retrieve an API token. This token acts as a bearer token for authenticating your requests to the Heroku Platform API. To get your token, run:

heroku auth:token

The command will output a long alphanumeric string. This is your API token. Treat this token as you would a password. Do not hardcode it directly into your applications if they are publicly accessible, and avoid committing it to version control systems. For production applications, consider using environment variables or a secure secret management system to store and access your API token. For local development, storing it in an environment variable is a common practice.

Your first request

Once you have your API token, you can make your first authenticated request to the Heroku Platform API. The API base URL is https://api.heroku.com. All requests must include an Authorization header with your bearer token.

Example: Listing your applications

A good starting point is to list your existing Heroku applications. This endpoint is /apps. Using curl, you can make this request as follows. Replace <YOUR_HEROKU_API_TOKEN> with the token you generated in the previous step.

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

This command performs an HTTP GET request to the /apps endpoint. The Accept header specifies the API version (version 3 is the current stable version) and the desired media type (JSON). The Authorization header carries your bearer token, authenticating your request.

Expected Response

A successful response will return a JSON array containing details of your Heroku applications. If you have no applications, it will return an empty array ([]). Each application object will include properties like id, name, owner, and created_at. For example:

[
  {
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "name": "my-example-app",
    "owner": {
      "email": "[email protected]",
      "id": "fedcba98-7654-3210-fedc-ba9876543210"
    },
    "created_at": "2023-01-01T12:00:00Z",
    "updated_at": "2023-01-01T12:00:00Z",
    "stack": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "heroku-22"
    },
    "released_at": "2023-01-01T12:30:00Z",
    "buildpack_provided_description": "Ruby/Rack",
    "git_url": "https://git.heroku.com/my-example-app.git",
    "web_url": "https://my-example-app.herokuapp.com/"
    // ... other properties
  }
]

If you encounter an error, the response will typically include an HTTP status code indicating the issue (e.g., 401 Unauthorized if your token is invalid or missing) and a JSON error object with a message field explaining the problem. Consult the Heroku Platform API reference documentation for detailed error codes and explanations.

Common next steps

After successfully making your first API call, you can explore more advanced functionalities of the Heroku Platform API:

• Manage Applications: Create new applications, update existing ones, or delete them. Endpoints like POST /apps and PATCH /apps/{app_id_or_name} allow for comprehensive application lifecycle management.
• Configure Dynos: Adjust dyno sizes, scale dyno processes, or restart dynos. This is performed via endpoints such as PATCH /apps/{app_id_or_name}/formation.
• Manage Add-ons: Provision, configure, and deprovision Heroku add-ons for your applications, leveraging endpoints like POST /apps/{app_id_or_name}/addons.
• Environment Variables: Set, retrieve, or unset configuration variables for your applications using the /apps/{app_id_or_name}/config-vars endpoint.
• Webhooks: Set up webhooks to receive real-time notifications about changes to your applications or resources, which can be useful for integrating with CI/CD pipelines or monitoring tools.
• Use a Client Library: For more complex integrations, consider using a dedicated HTTP client library in your preferred programming language, such as requests for Python or node-fetch for Node.js, to simplify API interaction compared to raw curl commands.
• Explore the Heroku Platform API Reference: The official Heroku Platform API reference provides comprehensive documentation on all available endpoints, request/response formats, and authentication details.

Troubleshooting the first call

If your first API call does not return the expected results, consider the following common issues:

• Authentication Errors (401 Unauthorized):
  • Incorrect Token: Double-check that the API token in your Authorization: Bearer header is correct and hasn't expired. Regenerate it using heroku auth:token if unsure.
  • Missing Header: Ensure the Authorization header is present and correctly formatted (Authorization: Bearer <YOUR_TOKEN>).
  • Token Scope: Verify that the token has the necessary permissions. Tokens generated via heroku auth:token typically have broad access, but custom OAuth applications might have restricted scopes.
• Invalid Accept Header (406 Not Acceptable):
  • Incorrect Version: Ensure the Accept header specifies application/vnd.heroku+json; version=3. Using an incorrect version or media type can lead to errors.
• Resource Not Found (404 Not Found):
  • Incorrect Endpoint: Verify the URL path for the endpoint you are trying to access. The API reference documentation lists all valid paths.
  • Application Name/ID: If you're targeting a specific application, ensure its name or ID is correct and belongs to your account.
• Network Issues:
  • Internet Connectivity: Confirm your machine has an active internet connection.
  • Firewall/Proxy: Check if any local firewall or corporate proxy settings are interfering with outgoing HTTP requests to api.heroku.com.
• CLI Login State: While the API token is separate, ensuring your CLI is logged in (heroku login) can help verify overall account access and provide a baseline for troubleshooting.

For more detailed error troubleshooting, consult the Heroku Platform API error documentation, which provides specific error codes and their meanings.