Heroku Audit Trail Log Ingestion via API Polling

This guide explains how to configure RunReveal to poll Heroku Enterprise audit trail events (e.g., app creation, destruction, add-on management, collaborator changes, team membership updates) using the Heroku Platform API.

Prerequisites

• Heroku Enterprise account access
  You need a Heroku Enterprise organization with audit trail capabilities.
• Heroku API token with organization access
  Token must have read permissions for your enterprise organization’s audit trail.
• RunReveal account with permissions to add sources and view logs (admin/editor)
  Ability to add sources and view logs.

Step 1: Create Heroku Source in RunReveal

1. Navigate to Sources in RunReveal
2. Look for *Heroku source tile
3. Provide a descriptive Source Name (e.g., “Heroku” or “Heroku Audit Prod”)
4. Add your Heroku Enterprise Account ID and generated API Token to the tile from the steps below.

Step 2: Obtain Your Enterprise Account ID

The Enterprise Account ID is tied to your Heroku Enterprise organization identifier.

Finding Your Enterprise Account ID:

Method 1: Heroku CLI

# Install Heroku CLI if not already installed
npm install -g heroku
 
# Login to your account
heroku login
 
# List organizations you have access to
heroku orgs
 
# Example output:
# your-company-name (enterprise)

Method 2: API Request to return Enterprise Account Names and IDs

# Using your API token (see Step 3 below)
curl -n https://api.heroku.com/enterprise-accounts \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.heroku+json; version=3"

Step 3: Generate Heroku API Token

You need a Heroku API token with audit trail access permissions. The token needs to be created by a user with Enterprise Admin permissions and will have the prefex ”HRKU-”. You can validate the token works by calling the api endpoints for audit trail events from Heroku.

Creating a Heroku API Token via CLI:

# Login to Heroku
heroku login
 
# Create a new authorization with audit permissions
heroku authorizations:create --description "RunReveal Audit Trail"
 
# Example output:
# Client:      <client-id>
# ID:          <auth-id>
# Description: RunReveal Audit Trail
# Scope:       global
# Token:       <your-api-token>

Important: Copy the token immediately after creation - it won’t be shown again.

Required Permissions

Your API token must have access to:

• Organization audit events: read scope
• Enterprise account access: Must be a member of the enterprise organization

Step 4: Validate Data Collection

1. Return to RunReveal and open your source tile for Heroku page
2. Confirm that events are being collected (initial polling may take 5 minutes)
3. Search in Explorer or use Native AI Chat to inspect recent Heroku audit events
4. Look for the heroku_logs table with your source ID filter

Testing Your Configuration

Validate your credentials before saving in RunReveal:

# Test API token and enterprise access
curl -n https://api.heroku.com/enterprise-accounts/YOUR_ENTERPRISE_ACCOUNT_ID/events \
  -H "Authorization: Bearer YOUR_ENTERPRISE_API_TOKEN" \
  -H "Accept: application/vnd.heroku+json; version=3"
 
# Should return recent audit events JSON

Helpful Links

• Heroku Platform API Reference - Audit Trail
• Heroku Enterprise Audit Trail Documentation
• Managing API Tokens in Heroku