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:
- 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 anID
andsecret
which are needed to connect to the API. - 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.)
- 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:
-
-n
as shown in many examples is not needed (this tellscurl
to use a local .netrc file for credentials), and - 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