Getting Started with the Platform API

Table of Contents [expand]

Prerequisites
Authentication
Calling the API
Alternatives
Wrap-up

Last updated July 02, 2026

This is a brief guide to help you get started with the Heroku Platform API. For a detailed reference, please see the Platform API Reference article.

Prerequisites

A shell with curl
A Heroku user account. Signup is free and instant.

Samples

The samples below use curl simply for convenience. We recommend using your favorite programming language and a HTTP library with the API.

Alternatively, several client libraries are available:

Authentication

Authentication is passed in the Authorization header with a value set to Bearer {HEROKU_TOKEN}. The examples in this article use {HEROKU_TOKEN} as a placeholder for your authentication token.

If you’re using curl and logged in with the Heroku CLI, you can retrieve your token from your system keychain and set it to a variable or environment variable. The code example shows how to set your token to a variable on macOS, Windows, and Linux systems:

// For macOS systems
TOKEN=$(security find-generic-password -s "heroku-cli" -a "{your email}" -w)

// For Windows systems (PowerShell)
$vault = New-Object Windows.Security.Credentials.PasswordVault
$credential = $vault.Retrieve("heroku-cli", "{your email}")
$TOKEN= $credential.Password

// For Linux systems
TOKEN=$(secret-tool lookup service "heroku-cli" account "{your email}")

If you’re using .netrc for CLI authentication, you can use curl -n to automatically set this header to the same token as the CLI. You can also retrieve this token with heroku auth:token, however it’s only valid for a maximum of 1 year by default.

You can create a non-expiring token by running heroku authorizations:create:

$ heroku authorizations:create -d "getting started token"
Creating OAuth Authorization... done
Client:      <none>
ID:          a6e98151-f242-4592-b107-25fbac5ab410
Description: getting started token
Scope:       global
Token:       cf0e05d9-4eca-4948-a012-b91fe9704bab
Updated at:  Fri Jun 01 2018 13:26:56 GMT-0700 (PDT) (less than a minute ago)

Note for Federated Users

If you use SSO (your user account is associated with an identity provider) and attempt to create a non-expiring token, you get the following error message: "This account is a federated account. Federated accounts cannot issue OAuth authorizations."

To connect to the API via non-expiring token, we recommend creating a separate user, inviting them to your Heroku organization, but not adding them to your identity provider. That user can then generate and manage tokens used by your organization.

Calling the API

Here’s how to create an app with curl using your token stored in the HEROKU_API_KEY environment variable:

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

On Windows, it’s defined as:

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

Alternatively, here’s how to create an app with curl using the token from the .netrc file:

$ curl -nX POST https://api.heroku.com/apps \
-H "Accept: application/vnd.heroku+json; version=3"

The API returns JSON with details of the newly created app:

{
  "created_at":"2013-05-21T22:36:48-00:00",
  "id":"01234567-89ab-cdef-0123-456789abcdef",
  "git_url":"git@heroku.com:cryptic-ocean-8852.git",
  "name":"cryptic-ocean-8852",
  ...
}

You can also query the API for info on the app you created by passing the ID in the path:

$ curl -nX GET https://api.heroku.com/apps/01234567-89ab-cdef-0123-456789abcdef \
-H "Accept: application/vnd.heroku+json; version=3"

You can also list all the apps that you own or collaborate on:

$ curl -nX GET https://api.heroku.com/apps \
-H "Accept: application/vnd.heroku+json; version=3"

Let’s update the name of the app we created above by making a PATCH request to the same path you used for info:

$ curl -nX PATCH https://api.heroku.com/apps/01234567-89ab-cdef-0123-456789abcdef \
-H "Accept: application/vnd.heroku+json; version=3" \
-H "Content-Type: application/json" \
-d "{\"name\":\"my-awesome-app\"}"

You can also use the name to query the app, which is especially handy when you have changed it to something more memorable:

$ curl -n https://api.heroku.com/apps/my-awesome-app \
-H "Accept: application/vnd.heroku+json; version=3"

Finally, you can clean up and delete the test app:

$ curl -nX DELETE https://api.heroku.com/apps/01234567-89ab-cdef-0123-456789abcdef \
-H "Accept: application/vnd.heroku+json; version=3"

Alternatives

The Heroku API plugin can be used to make arbitrary commands to the CLI:

$ heroku plugins:install @heroku-cli/plugin-api
$ heroku api POST /apps --body '{"name": "example-app"}'
POST api.heroku.com/apps... 201
{
  "name": "example-app",
  "region": {
    "id": "59accabd-516d-4f0e-83e6-6e3757701145",
    "name": "us"
  },
  "updated_at": "2018-06-01T21:00:41Z",
  "web_url": "https://example-app-1234567890ab.herokuapp.com/",
  ...
}

httpie is a useful cURL replacement that is a bit more user friendly. It automatically uses the authentication credential from netrc and it assumes you’re POSTing JSON by default:

$ http PATCH https://api.heroku.com/apps/example-app/config-vars \
"Accept:application/vnd.heroku+json; version=3" \
RAILS_ENV=production
HTTP/1.1 200 OK
Cache-Control: private, no-cache
Content-Encoding: gzip
Content-Length: 672
Content-Type: application/json
...
{
    "DATABASE_URL": "postgres://pg",
    "RAILS_ENV": "production"
}

Wrap-up

This tutorial demonstrates how to call the Heroku Platform API using curl, but you can transfer this approach to whatever language and environment you favor. The tutorial focused specifically on creating, updating and deleting apps. The API has many more resources available, including add-ons, config vars and domains. They all work quite similarly to apps and detailed information can be found in the API reference.

Categories