How can my off platform application use the Heroku API to obtain my app's config vars or DB credentials?

Issue

You want to understand how to enable your on-prem application to retrieve current config vars from your Heroku app such as the current db connection string.

Resolution

OAuth and Accessing the Heroku API: Three methods explained below.

Method 1: OAUTH FLOW

Using OAuth authorization with the API is documented here within the Platform API reference. The authorization section of the article also links to an article on OAuth where the OAuth flow between a client application and the API is described in more detail.

The OAuth flow and steps to get access to and then query a Heroku app’s config vars will resemble the following steps:

1. The client application, for example an on-premise reporting application, will have to be registered as a client with an OAuth callback URL . Once registered, the client will have an ID and secret which are needed to connect to the API.
2. The client application will then need to authorize with the API according to the OAuth Flow which completes with the token exchange. (Note that the OAuth flow is necessarily elaborate for security.)
3. Subsequent API requests such as the request to get the config vars should authenticate by adding the access token’s token value to the Authorization header.

Method 2: Direct Authorization

Direct Authorization requests a token from the authorization API that will be used for successive calls to the API.

This method passes an account's username and password in basic auth (base64 encoded and passed as the Authorization header). Note that base64 encoded username:password is still sensitive information and should be treated as such and requests should use SSL.

Below is an example of how to obtain the API token using curl (see this example response to see the returned token).

AUTH=$(echo -ne "$BASIC_AUTH_USER:$BASIC_AUTH_PASSWORD" | base64 )

curl -X POST https://api.heroku.com/oauth/authorizations \
  -H "Accept: application/vnd.heroku+json; version=3" \
  -H "Authorization: Basic $AUTH" \
  -H "Content-type: application/json"

Using the api_token retrieved above, the API call to retrieve the config vars for an app will take the following form:

curl -H "Authorization: Bearer <api_token>" \
  -H "Accept: application/vnd.heroku+json; version=3" \
  https://api.heroku.com/apps/<app_name>/config-vars

Method 3: Use the user's API token as Bearer Token

This last method is to simply use an API token from heroku auth:token for API calls but this token is a token that allows access to the user's entire account and is the least secure. Note also that it will be invalidated when you do things like password changes which is good if you need to invalidate the token but bad if that breaks functionality that is required. As such, we recommend only using it for your personal needs.

As such, this method is not recommended for production although it may be interesting as a POC or development but the API token should be treated carefully, not stored in code that will be backed up, or recorded in any log files that can be accessed widely.

Note that using this method, the curl examples seen in documented explanations will change as follows:

1. -n as shown in many examples is not needed (this tells curl to use a local .netrc file for credentials), and
2. an additional header is used to submit the API token as follows: -H "Authorization: Bearer <token_returned_by_heroku_auth:token>"

For example:

curl -H "Authorization: Bearer <api_token>" \
  -H "Accept: application/vnd.heroku+json; version=3" \
  https://api.heroku.com/apps/<app_name>/config-vars