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
      • Working with Bundler
      • Rails Support
    • Python
      • Background Jobs in Python
      • Working with Django
    • Java
      • Working with Maven
      • Java Database Operations
      • 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
  • Migrating to Platform API for Partners

Migrating to Platform API for Partners

English — 日本語に切り替える

Last updated October 03, 2022

Table of Contents

  • Get All Apps endpoint replacement
  • Get App Info endpoint replacement
  • Update Config Vars endpoint replacement

If you your add-on uses our Legacy Add-on Partner App Info API, follow this guide to replace all calls to the legacy API with calls to Platform API for Partners. We will be removing support for the legacy API no later than July 3, 2023. If there are any changes to the deprecation timeline, we’ll update this article and announce it via the Heroku Changelog accordingly. For more information on the Add-on Partner App Info API end of life, see our FAQ article.

Your add-on must implement Add-on Partner API V3 before you can replace your calls to the legacy App Info API with calls to our current Platform API. If you built your add-on before May 2018 and haven’t migrated previously, your add-on integration still uses our legacy Add-on Partner API V1. You will need to follow this guide to migrate your add-on to our current integration API before attempting the endpoint replacements described here.

The Platform API for Partners allows add-ons to access a subset of our main Platform API via scoped OAuth tokens. This allows add-on partners to integrate more deeply and securely into the Heroku ecosystem, and fully replaces our legacy Add-on Partner App Info API. Moving forward, it will be the only way for your add-on services to update add-on config vars and retrieve app, collaborator, attachment and other add-on resource specific metadata.

Our legacy App Info API provides three endpoints of interest for add-on providers:

  • Get All Apps.
  • Get App Info.
  • Update Config Vars.

Get All Apps endpoint replacement

The legacy Get All Apps endpoint allows you get a list of apps that have installed your add-on.

Example Legacy Get All Apps request to be replaced

$ curl https://logcapture-staging:6349E6585913eD9a1@api.heroku.com/vendor/apps
[
  {
    "callback_url": "https://api.heroku.com/vendor/apps/fc045862-3954-4869-80d3-0a69063f995f",
    "heroku_id": "app888888888@heroku.com",
    "name": "test-app-1",
    "resource": {
      "uuid": "fc045862-3954-4869-80d3-0a69063f995f",
      "name": "logcapture-staging-silhouetted-45667"
    },
    "plan": "test",
    "provider_id": "provider_id_12345"
  },
  {
    "callback_url": "https://api.heroku.com/vendor/apps/e5d0dc92-0e7d-4720-af67-0ec40198421f",
    "heroku_id": "app878787878@heroku.com",
    "name": "test-app-2",
    "resource": {
      "uuid": "e5d0dc92-0e7d-4720-af67-0ec40198421f",
      "name": "logcapture-staging-concave-99081"
    },
    "plan": "test",
    "provider_id": "provider_id_67890"
  }
]

Platform API for Partners can’t provide an endpoint where you can fetch a list of applications that have your add-on installed due to the fact that authentication is token based and the tokens are scoped to a specific resource for which they were granted. To overcome this limitation, we have added a new Apps endpoint to the Add-ons API v3 that can be used for this purpose.

Add-ons API v3 is our public API powering your company users’ interactions within the Partner Portal, but also enabling add-on providers to access and update that information programmatically.

In order to use the Apps endpoint you will need to authenticate against Add-ons API v3 with an authorization token belonging to one of the registered company users. Heroku users can generate temporary or long-lived authorizations through Dashboard (User menu → Account Settings → Applications → Authorizations) or Heroku CLI tool.

Example long-lived authorization creation

$ heroku authorizations:create -d "Add-ons API v3 access token"
Creating OAuth Authorization... done
Client:      <none>
ID:          e844f998-4852-4176-bd35-9d5b74e18f46
Description: Add-ons API v3 access token
Scope:       global
Token:       0b6cbe5f-9d1e-4277-b842-dd1361b60909

Use the generated access token as a Bearer token on the Authorization header when making the request to Add-ons API v3.

Example Apps request to Add-ons API V3

$ curl https://addons.heroku.com/api/v3/addons/logcapture-staging/apps \
-H "Authorization: Bearer 0b6cbe5f-9d1e-4277-b842-dd1361b60909" \
-H "Accept: application/json"
[
  {
    "callback_url": "https://api.heroku.com/addons/fc045862-3954-4869-80d3-0a69063f995f",
    "id": "95c71f9b-9068-4829-b3b3-6e0472db7a04",
    "name": "test-app-1",
    "resource": {
      "uuid": "fc045862-3954-4869-80d3-0a69063f995f",
      "name": "logcapture-staging-silhouetted-45667"
    },
    "plan": "test",
    "provider_id": "fc045862-3954-4869-80d3-0a69063f995f"
  },
  {
    "callback_url": "https://api.heroku.com/addons/e5d0dc92-0e7d-4720-af67-0ec40198421f",
    "id": "72657576-cfa5-4130-9d99-92e440549168",
    "name": "test-app-2",
    "resource": {
      "uuid": "e5d0dc92-0e7d-4720-af67-0ec40198421f",
      "name": "logcapture-staging-concave-99081"
    },
    "plan": "test",
    "provider_id": "provider_id_67890"
  }
]

Responses from both the legacy API and Add-ons API V3 share a common pattern, but there are some fundamental differences to keep into account:

  • heroku_id was a legacy app identifier, now deprecated and has been removed in favor of the current id. The new identifier can be used to fetch detailed app information as described in the next section.
  • callback_url was kept for compatibility reasons, but the URI now points to the Add-on Info endpoint in Platform API instead of the legacy API. It’s the same value sent with the initial provisioning request.
  • provider_id was kept for add-on provider reference, but it’s no longer used as the identifier on requests made to your Add-on Partner API integration endpoints. It’s the value associated to the id attribute you set in the response to the initial provisioning request.

Result Pagination

Results larger than 4,000 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 pagination header

Link: <https://addons.heroku.com/api/v3/addons/logcapture-staging/apps?offset=0>; rel="prev", <https://addons.heroku.com/api/v3/addons/logcapture-staging/apps?offset=8000>; 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 endpoint replacement

If your add-on service implementation uses the Legacy Add-on Partner App Info API to obtain detailed information about an app by means of the Get App Info endpoint, replace those calls with requests to the App Info endpoint from Platform API.

Example Legacy Get App Info request to be replaced

$ curl https://logcapture-staging:6349E6585913eD9a1@api.heroku.com/vendor/apps/provider_id_12345
{
  "callback_url": "https://api.heroku.com/vendor/apps/fc045862-3954-4869-80d3-0a69063f995f",
  "config": {
    "LOGCAPTURE_STAGING_API_KEY": "BiB5GNfw+g3P0IUR8bJr1fKY",
    "LOGCAPTURE_STAGING_URL": "https://logcapture-staging.herokuapp.com/kR2Qvn8gELmdZwZU"
  },
  "domains": [
    "test-app-1.herokuapp.com"
  ],
  "id": "app888888888@heroku.com",
  "name": "test-app-1",
  "owner_email": "developer@logcapture.com",
  "owner": {
    "uuid": "a3bcc594-cd28-4517-ac3a-ab23aa9b6841",
    "email": "developer@logcapture.com"
  },
  "region": "amazon-web-services::us-east-1",
  "resource": {
    "uuid": "fc045862-3954-4869-80d3-0a69063f995f",
    "name": "logcapture-staging-silhouetted-45667"
  },
  "plan": "test",
  "logplex_token": "t.61ebeb54-deba-438e-90a6-16ce6784c338"
}

Notice that when replacing the legacy App Info endpoint with the App Info endpoint from Platform API, the JSON response won’t include related entities like resource and config vars as there are specific endpoints to retrieve that info. You can see a list of available endpoints in the Platform API for Partners article.

Example App Info request from Platform API

$ curl https://api.heroku.com/apps/95c71f9b-9068-4829-b3b3-6e0472db7a04 \
-H "Authorization: Bearer 9ebed010-233d-4de3-9f2f-fdfeddddd9c7" \
-H "Accept: application/vnd.heroku+json; version=3"
[
  {
    "acm": false,
    "archived_at": null,
    "buildpack_provided_description": null,
    "build_stack": {
      "id": "3bcd644c-3108-4c40-8969-2aa29947d1c6",
      "name": "heroku-18"
    },
    "created_at": "2020-06-11T17:23:00Z",
    "id": "95c71f9b-9068-4829-b3b3-6e0472db7a04",
    "git_url": "https://git.heroku.com/test-app-1.git",
    "maintenance": false,
    "name": "test-app-1",
    "owner": {
      "uuid": "a3bcc594-cd28-4517-ac3a-ab23aa9b6841",
      "email": "developer@logcapture.com"
    },
    "region": {
      "id": "8271a929-df76-4021-855f-feb83fee000e",
      "name": "us"
    },
    "organization": null,
    "team": null,
    "space": null,
    "internal_routing": null,
    "released_at": "2020-11-10T20:53:00Z",
    "repo_size": null,
    "slug_size": null,
    "stack": {
      "id": "3bcd644c-3108-4c40-8969-2aa29947d1c6",
      "name": "heroku-18"
    },
    "updated_at": "2021-09-07T06:11:28Z",
    "web_url": "https://test-app-1.herokuapp.com/"
  }
]

Update Config Vars endpoint replacement

Update Config Vars endpoint from the Legacy Add-on Partner App Info API allows you to set or remove config var values controlled by your add-on service. Requests sent to that endpoint should be replaced by calls to the Add-on Config Update endpoint from the Platform API for Partners.

Example Legacy Update Config Vars request to be replaced

$ curl -X PUT https://logcapture-staging:6349E6585913eD9a1@api.heroku.com/vendor/apps/95c71f9b-9068-4829-b3b3-6e0472db7a04 \
-H 'Content-Type: application/json'
-d '{"config":{"LOGCAPTURE_STAGING_URL":"https://logcapture-staging.herokuapp.com/Hgp35ph6YLeaGnPz"}}'

Notice that the JSON payload for the old endpoint consisted of an object containing one single config key with an object value where the keys are the config var names to update and the values contain the literal value to be assigned. For the new endpoint, the JSON payload consists, similarly, of an object with a single config key, However, its value is an array of objects, each of which describes a single config var to update and contains two keys: name and value, whose values are the name of the config var to update and the new value to set respectively.

Example Add-on Config Update request

$ curl -X PATCH https://api.heroku.com/addons/fc045862-3954-4869-80d3-0a69063f995f/config \
-H "Authorization: Bearer 9ebed010-233d-4de3-9f2f-fdfeddddd9c7" \
-H "Content-Type: application/json"
-H "Accept: application/vnd.heroku+json; version=3"
-d '{"config":[{"name":"LOGCAPTURE_STAGING_URL","value":"https://logcapture-staging.herokuapp.com/Hgp35ph6YLeaGnPz"}]}'
[
  {
    "name": "API_KEY",
    "value": "BiB5GNfw+g3P0IUR8bJr1fKY",
  },
  {
    "name": "URL",
    "value": "https://logcapture-staging.herokuapp.com/Hgp35ph6YLeaGnPz"
  }
]

Keep reading

  • Building Add-ons

Feedback

Log in to submit feedback.

What Is an Add-on? Migrating to V3 of the Add-on Partner API

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