Heroku Workloads

The Heroku Workloads Integration allows your product to fetch all deployed applications (workloads) from a user’s Heroku account — including their app names, dynos, regions, statuses, and associated configurations.

This integration is commonly used for:

• Asset inventory
• Deployment monitoring
• Cloud workload security

Credentials Needed

To connect to the Heroku Platform API, you need to authenticate using a Heroku API Key associated with the user or team account.

Required Credentials:

• Heroku API Key
• (Optional) Heroku Email (for display/reference)

The API key can be generated from your Heroku Dashboard or via CLI and should always be stored securely.

Permissions Needed / API Scopes

Heroku’s API keys are account-level keys that grant full access to all apps the user can access.
There are no granular scopes like OAuth.

If using OAuth2 (for user-based integrations), request the following scopes:

• global
• identity
• read — to fetch app/workload metadata

Functionality

Endpoint	Description	Permission Needed
/apps	List all apps (workloads)	Requires valid Heroku API key
/apps/{app_id_or_name}	Get app details	Requires valid Heroku API key
/apps/{app_name}/dynos	List dynos (running containers)	Requires valid Heroku API key
/apps/{app_name}/collaborators	List collaborators or teams	Requires valid Heroku API key

Creating Users / Access Tokens

Option 1: Generate Heroku API Key via Dashboard

1. Log in to your Heroku Dashboard
2. Scroll to the API Key section
3. Click Reveal API Key
4. Copy and securely store your Heroku API Key
   Example: heroku_api_key_123456789

Option 2: Generate via Heroku CLI

# Log in to your Heroku account
heroku login

# Get the API key for your user
heroku auth:token

The command returns your current Heroku API key.

Test Connectivity

You can test your Heroku API credentials using curl or any REST client:

Fetch all workloads (apps)

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

Example Response:

[
  {
    "id": "b1b3c5e4-xxxx-xxxx-xxxx-123456789abc",
    "name": "my-sample-app",
    "owner": {"email": "user@example.com"},
    "region": {"name": "us"},
    "stack": {"name": "heroku-22"},
    "created_at": "2025-01-10T10:00:00Z",
    "updated_at": "2025-01-11T09:20:00Z",
    "released_at": "2025-01-11T09:19:00Z",
    "git_url": "https://git.heroku.com/my-sample-app.git",
    "web_url": "https://my-sample-app.herokuapp.com/"
  }
]

List dynos (containers) under each app

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

Example Dyno Response:

[
  {
    "id": "dd3eabc1-xxxx-xxxx-xxxx-123456789abc",
    "name": "web.1",
    "state": "up",
    "type": "web",
    "command": "npm start",
    "size": "standard-1x",
    "updated_at": "2025-01-11T09:21:00Z"
  }
]

Save the Results in the Platform and Create Connection

In your platform’s integration setup, securely store:

• HEROKU_API_KEY
• (Optional) HEROKU_EMAIL

Then:

1. Create a connection labeled Heroku Workloads Integration
2. Test the connection by retrieving all apps using /apps
3. Save the list of apps (workloads) and dynos in your database or cache for later analysis

Best Practices

• Store API keys securely using your product’s encrypted secret vault or key management system
• Avoid hardcoding credentials in code
• Rotate API keys regularly and revoke unused ones
• Limit API usage to read-only endpoints when possible
• Use Heroku OAuth2 for multi-user SaaS integrations instead of a shared API key
• Cache workload data locally to minimize repeated API calls
• Respect Heroku’s API rate limits (approximately 4500 requests/hour per user)
• Use exponential backoff for 429 Too Many Requests responses
• Periodically sync workloads (apps, dynos) to keep your platform’s inventory updated