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
      • Working with Django
      • Background Jobs in Python
    • 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 Performance
      • Postgres Data Transfer & Preservation
      • Postgres Availability
      • Postgres Special Topics
    • Heroku 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)
    • 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
  • 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 22 December 2020

Table of Contents

  • Get All Apps
  • Get App Info
  • Update Config Vars
  • Error responses
  • Counting add-on beta users

This API will be deprecated in favor of a newer version. To learn about the current API, check out Add-on Partner API

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"
  }
}'

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

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