Last updated 13 October 2020

In order to manage users of your add-on, you likely have at least one login tool set up. Heroku provides the Add-ons Single Sign-on integration, which allows users to login with their Heroku account directly from their app’s dashboard, however some add-ons have their own login systems or use third-party OAuth services like GitHub to gain additional capabilities. Having a consolidated list of logins between the Add-ons SSO service and your own login system can make it much easier to manage permissions in your add-on.

This article describes how to create a “user access list” by making requests to the Platform API for Partners.

Prerequisites

• Access and use of the Platform API for Partners
• Recording Heroku add-on resource UUIDs on provision or by fetching from the existing Get App Info API endpoint – we highly recommend that you start saving them off of the Get App Info API if you aren’t already, since the resource UUID will never change and is the primary ID for accessing the Platform API for Partners.

Concepts

There are two concepts in Heroku that you must be familiar with to build this functionality.

The first concept is app collaborators. These are users which have been granted access to an app by an app’s owner.

The second concept is an Team and the team’s member list. A user can appear on either an app’s collaborators list, or on a member list of an team which owns an app. You will have to request both the app’s collaborators list and the team members list to build a full list of users with access to an add-on.

Implementation

To get a full list of Heroku users with access to an app, you’ll need to request:

• GET https://api.heroku.com/addons/:resource_uuid -> grab the app name
• GET /apps/:app_name/collaborators -> A list of app collaborator users
• GET /apps/:app_name -> Check for “team” object as part of the serialized response, save the Team’s UUID if present
• If team app per above: GET /teams/:team_uuid/members

To detect whether an app is owned by an org, you will look in GET /apps/:app_name‘s response for an "team" object. Pull out the Team’s UUID from this object. Then request the GET /teams/:org_uuid/members endpoint. Combine this list with the app collaborators list from above. If the email address given during the SSO request appears in this combined list, that user should be able to access the add-on for the specified application.

You need to repeat this process for each app in question, using the resource-scoped token for that application under the Platform API for Partners.

In the future, we’d like to open up some sort of standardized endpoint that indicates what users an add-on has access to through all apps or particular apps, but we don’t have that pattern for indicating access in our API yet. If you have suggestions for how such an endpoint might work, please get in touch with the Ecosystem team.