Skip Navigation
Show nav
Heroku Dev Center
  • Get Started
  • Documentation
  • Changelog
  • Search
  • Get Started
    • Node.js
    • Ruby on Rails
    • Ruby
    • Python
    • Java
    • PHP
    • Go
    • Scala
    • Clojure
  • Documentation
  • Changelog
  • More
    Additional Resources
    • Home
    • Elements
    • Products
    • Pricing
    • Careers
    • Help
    • Status
    • Events
    • Podcasts
    • Compliance Center
    Heroku Blog

    Heroku Blog

    Find out what's new with Heroku on our blog.

    Visit Blog
  • Log inorSign up
View categories

Categories

  • Heroku Architecture
    • Dynos (app containers)
    • Stacks (operating system images)
    • Networking & DNS
    • Platform Policies
    • Platform Principles
  • Command Line
  • Deployment
    • Deploying with Git
    • Deploying with Docker
    • Deployment Integrations
  • Continuous Delivery
    • Continuous Integration
  • Language Support
    • Node.js
    • Ruby
      • Rails Support
      • Working with Bundler
    • Python
      • Background Jobs in Python
      • Working with Django
    • Java
      • Working with Maven
      • Java Database Operations
      • Working with the Play Framework
      • Working with Spring Boot
      • Java Advanced Topics
    • PHP
    • Go
      • Go Dependency Management
    • Scala
    • Clojure
  • Databases & Data Management
    • Heroku Postgres
      • Postgres Basics
      • Postgres Getting Started
      • Postgres Performance
      • Postgres Data Transfer & Preservation
      • Postgres Availability
      • Postgres Special Topics
    • Heroku Data For Redis
    • Apache Kafka on Heroku
    • Other Data Stores
  • Monitoring & Metrics
    • Logging
  • App Performance
  • Add-ons
    • All Add-ons
  • Collaboration
  • Security
    • App Security
    • Identities & Authentication
    • Compliance
  • Heroku Enterprise
    • Private Spaces
      • Infrastructure Networking
    • Enterprise Accounts
    • Enterprise Teams
    • Heroku Connect (Salesforce sync)
      • Heroku Connect Administration
      • Heroku Connect Reference
      • Heroku Connect Troubleshooting
    • Single Sign-on (SSO)
  • Patterns & Best Practices
  • Extending Heroku
    • Platform API
    • App Webhooks
    • Heroku Labs
    • Building Add-ons
      • Add-on Development Tasks
      • Add-on APIs
      • Add-on Guidelines & Requirements
    • Building CLI Plugins
    • Developing Buildpacks
    • Dev Center
  • Accounts & Billing
  • Troubleshooting & Support
  • Integrating with Salesforce
  • Extending Heroku
  • Building Add-ons
  • Add-on APIs
  • [Legacy] Add-on Partner App Info API

[Legacy] Add-on Partner App Info API

English — 日本語に切り替える

Last updated October 03, 2022

Table of Contents

  • Get All Apps
  • Get App Info
  • Update Config Vars
  • Log Drain Info
  • Log Drain Update
  • Counting add-on beta users

Heroku is deprecating Legacy Add-on App Info API, and it will EOL on July 3, 2023. For more information on the end of life, see our FAQ article.

This is a reference document for the API calls you can use to query information about your add-on installations. In these examples you are issuing the requests and Heroku is providing the response. All calls should use HTTP basic authorization, where the username must be set to the add-on manifest’s id (also known as slug) and the password to the one specified in the add-on manifest.

Get All Apps

Get a list of apps that have installed your add-on. The resource.uuid value corresponds with the uuid field sent during provision requests.

GET https://<manifest_id>:<manifest_password>@api.heroku.com/vendor/apps

Response Example

[
  {
    "callback_url": "https://api.heroku.com/vendor/apps/01234567-89ab-cdef-0123-456789abcdef",
    "heroku_id": "app123@heroku.com",
    "plan": "test",
    "provider_id": "1",
    "resource": {
      "uuid": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "addon-fluffy-6756"
    }
  },
  {
    "callback_url": "https://api.heroku.com/vendor/apps/abcdef12-3456-7890-abcd-ef1234567890",
    "heroku_id": "app456@heroku.com",
    "plan": "premium",
    "provider_id": "3",
    "resource": {
      "uuid": "abcdef12-3456-7890-abcd-ef1234567890",
      "name": "addon-vertical-9873"
    }
  }
]

The callback_url and heroku_id attributes returned in App Info API endpoints are for compatibility purposes only. We discourage partners from using them. Instead, use the Get App Info endpoint and provider_id attribute.

Result Pagination

Results larger than 4000 will be paginated. Pagination information is passed via the Link HTTP header. Use those URIs to navigate the pagination rather than constructing them in your client code.

Example

Link: <https://api.heroku.com/vendor/apps?offset=100>; rel="prev", <https://api.heroku.com/vendor/apps?offset=1000>; rel="next"

The possible rel values within that header are:

  • next: Shows the URL of the immediate next page of results.
  • prev: Shows the URL of the immediate previous page of results.

Get App Info

Get details on any of your add-on instances, including the name of the app, plan, and owner email. This is the endpoint that should be used to find the app name for communication with customers (do not use heroku_id as that will not be recognized by customers).

This endpoint will only return a 200 response after provisioning has completed. Trying to access App Info during a provisioning request will return a 404 response. Some fields are dependent on your add-on manifest and may be omitted.

GET https://<manifest_id>:<manifest_password>@api.heroku.com/vendor/apps/<app_identifier>

Where the app_identifier used must be one of the following (in descending order of preference):

  • provider_id
  • resource.uuid
  • heroku_id - note, we advise that you stop using this identifier for future compatibility with shareable add-on features.

Response Example

{
  "id": "app123@heroku.com",
  "callback_url": "https://api.heroku.com/vendor/apps/01234567-89ab-cdef-0123-456789abcdef",
  "config": {
    "MYADDON_URL": "http://myaddon.com/52e82f5d73"
  },
  "domains": [ "www.the-consumer.com", "the-consumer.com" ],
  "log_input_url": "https://token:t.abcdef12-3456-7890-abcd-ef1234567890@1.us.logplex.io/logs"
  "name": "myapp",
  "plan": "test",
  "owner_email": "glenn@heroku.com",
  "owner": {
    "uuid":  "31e71f4d-b0f6-4250-8c1a-f914b99adba2",
    "email": "glenn@heroku.com"
  },
  "region": "amazon-web-services::us-east-1",
  "resource": {
    "uuid": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "addon-fluffy-6756"
  }
}

Update Config Vars

Update config vars that were previously set for an application during provisioning.

You can only update config vars that have been declared in your add-on manifest.

The body should be a JSON string consisting on an object with only one config key set to an object of key-value pairs. Each pair must have the config var name as the key and the new value that should be assigned.

PUT https://<manifest_id>:<manifest_password>@api.heroku.com/vendor/apps/<provider_id>

Curl Example

$ curl -n -X PUT https://$MANIFEST_ID:$MANIFEST_PASSWORD@api.heroku.com/vendor/apps/$PROVIDER_ID \
-H "Content-Type: application/json" \
-d '{
  "config": {
    "MYADDON_URL": "https://myaddon.com/ABC123",
    "MYADDON_API_KEY": "0123456789abcdef"
  }
}'

Log Drain Info

Get details on an existing log drain URL set for an application during provisioning.

Log drain endpoints are blocked by default and must manually be opened to each Add-on Partner. Please open a new support ticket to let us know that you’re interested in using this endpoint if your requests get rejected with a 401 - Unauthorized HTTP error code.

GET https://<manifest_id>:<manifest_password>@api.heroku.com/vendor/log-drains/<log_drain_token>

Where the log_drain_token is the token sent with the original provision request.

Response Example

{
  "url": "https://example.com/drain"
}

Log Drain Update

Update the log drain URL that was previously set for an application during provisioning.

Log Drain endpoints are blocked by default and must manually be opened to each Add-on Partner. Please open a new support ticket to let us know that you are interested in using this endpoint if your requests are rejected with a 401 - Unauthorized HTTP error code.

The body should be a JSON string consisting of an object with only one url key set to the updated Log Drain URL.

PUT https://<manifest_id>:<manifest_password>@api.heroku.com/vendor/log-drains/<log_drain_token>

Curl Example

$ curl -n -X PUT https://$MANIFEST_ID:$MANIFEST_PASSWORD@api.heroku.com/vendor/log-drains/$LOG_DRAIN_TOKEN \
-H "Content-Type: application/json" \
-d '{
  "url": "https://example.com/new-drain"
}‘

Error responses

The following response codes will be returned depending on the underlying cause of the error:

401: An invalid username and password combination has been supplied and you have not been successfully authenticated. This error will also be returned if you try to use any of the Log Drain endpoints and your add-on has not been manually enabled to access them.

404: The requested app doesn’t exist (e.g., it has been deleted) or the add-on has been deprovisioned for this app.

Counting add-on beta users

Before an add-on can progress to the general availability stage, add-on providers are required to have at least 100 unique beta users testing the add-on.

To obtain your beta user count, follow these steps:

  1. Get all apps that have your add-on currently installed by using the Get All Apps endpoint and build a list of provider_ids.
  2. Using the Get App Info endpoint, once for each provider_id, build a list of app owner emails (attribute owner.email).
  3. Remove duplicate app owner emails to get a unique count.

Example implementation

This is an example Bash script using curl and standard *nix tools.

#!/bin/bash

MANIFEST_ID="<manifest_id>"
MANIFEST_PASSWORD="<manifest_password>"

function app_list {
  curl -s -X GET https://${MANIFEST_ID}:${MANIFEST_PASSWORD}@api.heroku.com/vendor/apps
}

function extract_app_provider_id {
  sed -n '/provider_id/! { d; }; /.*"provider_id":"\(.*\)"/ { s//\1/; p; }'
}

function app_info() {
  curl -s -X GET https://${MANIFEST_ID}:${MANIFEST_PASSWORD}@api.heroku.com/vendor/apps/$1
}

function extract_owner_email {
  sed -n '/owner_email/! { d; }; /.*\"owner_email\":"\(.*\)".*/ { s//\1/; p; }'
}

echo "Unique app owners for '${MANIFEST_ID}': $(for i in $(app_list | extract_app_provider_id); do app_info $i | extract_owner_email; done | sort -u | wc -l)"

Keep reading

  • Add-on APIs

Feedback

Log in to submit feedback.

Using Webhooks as an Add-on Partner Platform API for Partners

Information & Support

  • Getting Started
  • Documentation
  • Changelog
  • Compliance Center
  • Training & Education
  • Blog
  • Podcasts
  • Support Channels
  • Status

Language Reference

  • Node.js
  • Ruby
  • Java
  • PHP
  • Python
  • Go
  • Scala
  • Clojure

Other Resources

  • Careers
  • Elements
  • Products
  • Pricing

Subscribe to our monthly newsletter

Your email address:

  • RSS
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku Blog
    • Heroku News Blog
    • Heroku Engineering Blog
  • Heroku Podcasts
  • Twitter
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku
    • Heroku Status
  • Facebook
  • Instagram
  • Github
  • LinkedIn
  • YouTube
Heroku is acompany

 © Salesforce.com

  • heroku.com
  • Terms of Service
  • Privacy
  • Cookies
  • Cookie Preferences