Docs
Plugins
Sources
Heroku
Overview

Heroku Source Plugin

Latest: v3.3.1

The CloudQuery Heroku plugin extracts your Heroku data and loads it into any supported CloudQuery destination (e.g. PostgreSQL, BigQuery, Snowflake, and more).

Configuration

This example connects a Heroku account to a Postgres destination. The (top level) source spec section is described in the Source Spec Reference.

kind: source
spec: # Common source spec section
  name: heroku
  path: cloudquery/heroku
  version: "v3.3.1"
  tables: ["*"]
  destinations: ["postgresql"]

  spec: # Heroku specific section
    token: <YOUR_TOKEN_HERE>

Authentication

The CloudQuery Heroku plugin requires an OAuth token. After creating it, you will need to copy the token into your heroku.yml file:

  ...
  token: <Token HERE>

The value can also be exported as an environment variable (e.g. HEROKU_TOKEN), and used like this:

   ...
   token: ${HEROKU_TOKEN}

Option 1: Generate a token with the Heroku CLI

A token can be generated using the Heroku CLI.

  1. Install the Heroku CLI: Follow the official instructions (opens in a new tab) to install the Heroku CLI.
  2. Generate an OAuth token: With the Heroku CLI installed, use your terminal to run:
heroku authorizations:create --short --description="CloudQuery token" --scope="read,identity"

(For additional options for this command, such as expiry, see the Heroku CLI commands documentation (opens in a new tab))

Option 2: Generate a token with the Heroku API

It is also possible to manage OAuth tokens directly through the Heroku API. For more information, see the Heroku documentation (opens in a new tab).

A Note about OAuth Scopes

CloudQuery needs to be authenticated with your Heroku account's token in order to fetch information about your Heroku resources. CloudQuery requires only read permissions (we will never make any changes to your Heroku account or apps). Following the principle of least privilege, it is recommended to grant it read-only permissions. The --scope="read,identity" parameter suggested above achieves this.

However, certain Heroku resources require a global scope, even for reading. At the time of writing, these resources are:

  • app_webhook_deliveries
  • app_webhook_events
  • app_webhooks
  • credits
  • invoices
  • keys
  • oauth_authorizations
  • oauth_clients
  • permission_entities
  • team_features
  • team_invitations
  • team_invoices
  • team_members
  • team_spaces

If you are interested in fetching any of these resources, a global scope will be necessary. See the Heroku documentation for more information about OAuth scopes on Heroku (opens in a new tab).

Heroku Spec

This is the (nested) spec used by the Heroku source plugin.

  • token (string, required)

Heroku API token. See the Authentication section on how to generate it.

TablesConfiguration