[Legacy] Add-on Partner API Reference

Last updated February 06, 2024

Overview

The Add-on Partner API is used when Heroku calls your add-on service. In these examples Heroku is issuing the requests and your add-on is providing the responses.

Heroku is deprecating Legacy Add-on Partner API v1, and it will EOL on July 3, 2023. For more information on the v1 end of life, see our FAQ article.

General guidelines

Your add-on service must implement all the calls listed in this document. Any requests that are unable to be serviced should return a 422 response with an informative message for the user.

Authentication

All calls should be protected by HTTP basic auth with the add-on id (often referred to as the add-on identifier or slug) and password specified in your add-on manifest.

Idempotency

Requests MAY be sent multiple times (Heroku follows the pattern of at least once delivery), and endpoints MUST respond idempotently. For example, in the case of creating a resource multiple POSTs with the same parameters should only provision a single resource.

Validation

Request bodies MAY contain additional elements not currently documented here, and such requests should be treated as valid.

Timeouts

Your service SHOULD respond within 3 seconds. Currently, it MUST return within 25 seconds or the request will fail. This upper limit will be reduced over time at our discretion and based on our analysis.

If more time to respond is necessary, use the Async Partner API. An older alternative was to respond 202 Accepted as an acknowledgement that the provision will be fulfilled, and use the Platform API to set any necessary config vars when ready, however this alternative is deprecated and in the future any 202 response will trigger an async process.

Versioning

The current version of the API is version 3. This document describes a legacy version.

Response Bodies

All response bodies MUST contain valid JSON.

Exceptions

If your API CAN NOT fulfill a request, you SHOULD respond with an appropriate HTTP status code in the 4xx range if it is due to an invalid request (e.g. non-existent plan) or 5xx range if your API is experiencing unexpected errors. The error response body MUST contain valid JSON.

For 4xx and 5xx responses on provision and plan change requests, the message property from your JSON response will be displayed to the user. For all other responses, and when no message property is available, a generic error message will be displayed.

For common types of errors, it is recommended that your API add an id property to error payloads that contains a short keyword identifying the type of error. For an example, see how Heroku does it in our Platform API Reference. In the future, such identifiers may be exposed to partners in metrics and tooling for analysis. Failed Attempts to provision, deprovision etc, are available in the Partner Portal. We encourage you to monitor this list as it gives visibility into problems that customers are having.

Platform API

After your add-on is provisioned, you can use the Platform API to query information about your add-on installations or to update the Config Vars for your add-on. Previously we recommended using the App Info API for this purpose, but it is recommended that partners migrate to the Platform API.

Provision

A provision request from Heroku to your add-on service.

Parameters

Name Type Description Example
callback_url string The URL which should be used to retrieve updated information about the add-on and the app which owns it. https://api.heroku.com/vendor/apps/app1234@heroku.com
heroku_id string An identifier for the application which will own the add-on being provisioned. It does not uniquely identify the add-on itself. app1234@heroku.com
oauth_grant nullable object OAuth object details null
oauth_grant:code uuid may be exchanged for an access_token that is scoped to the resource being provisioned for use in the Platform API 01234567-89ab-cdef-0123-456789abcdef
oauth_grant:expires_at date-time the time at which the grant expires (ensure you have exchanged for a token before this time) 2016-03-03T18:01:31-0800
oauth_grant:type string the oauth grant type authorization_code
options object extra command line options passed in to the heroku addons:create command { "foo" : "bar", "baz" : "true" }
plan string the name of the plan to provision basic
region string Specifies the geographical region of the app that the add-on is being provisioned to—either amazon-web-services::us-east-1 or amazon-web-services::eu-west-1 are possible at this time. Use this to provision the resource in geographical proximity to the app, ignore it (if your add-on is not latency sensitive) or respond with an error if your add-on does not support apps in the region specified amazon-web-services::us-east-1

Optional Parameters

Name Type Description Example
log_input_url string Provided so that logs can be sent to the app’s log stream. This field is only present when configured in your manifest, by adding log_input to the requires field. For more information, see the article describing logplex input. https://token:t.01234567-89ab-cdef-0123-456789abcdef@1.us.logplex.io/logs
log_drain_token string Provided so that logs from the app can be sent to the log_drain_url specified by the partner. This field is only present when configured in your manifest, by adding syslog_drain to the requires field. For more information, see the article describing accessing application logs. d.01234567-89ab-cdef-0123-456789abcdef

Request Example

POST /heroku/resources HTTP/1.1
Host: addon-slug.herokuapp.com
Authorization: Basic YWRkb24tc2x1ZzpzdXBlci1zZWNyZXQ=
Content-Type: application/json
Accept: application/json

{
  "callback_url": "https://api.heroku.com/vendor/apps/app1234@heroku.com",
  "heroku_id": "app1234@heroku.com",
  "oauth_grant": {
    "code": "01234567-89ab-cdef-0123-456789abcdef",
    "expires_at": "2016-03-03T18:01:31-0800",
    "type": "authorization_code"
  },
  "options": { "foo" : "bar", "baz" : "true" },
  "plan": "basic",
  "region": "amazon-web-services::us-east-1",
  "log_input_url": "https://token:t.01234567-89ab-cdef-0123-456789abcdef@1.us.logplex.io/logs",
  "log_drain_token": "d.01234567-89ab-cdef-0123-456789abcdef"
}

Parameters

Name Type Description Example
id string MAY be a string (e.g. UUID) or integer value. It MUST be an immutable value that can be used to address your resource. 01234567-89ab-cdef-0123-456789abcdef

Optional Parameters

Name Type Description Example
message string Further instructions to the user after creating the add-on Resource has been created and is available!
config object Environment variables to be set on any applications that use this add-on. All environment variables that you send should have the same prefix: your add-on’s name, capitalized. However, within the context of a Heroku app, the prefix may be different for a variety of reasons. For example, if your add-on is named fast-db and you are setting FAST_DB_URL, the variable name on the application will default to FAST_DB_URL but would be PRIMARY_DB_URL if the user added the add-on with the prefix PRIMARY_DB. { "MYADDON_URL": "http://myaddon.com/52e82f5d73" }

Response Example

HTTP/1.1 202 Accepted

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "message": "Resource has been created and is available!",
  "config": { "MYADDON_URL": "http://myaddon.com/52e82f5d73" }
}

Plan Change

When a user requests a plan change for an installed add-on, Heroku will send a PUT request to your API.

If you CAN NOT support plan changes, respond with status code 422 or 503 and return a message to display to the user, as per the description below. For example, if it is impossible to change between the users current plan and the requested plan, a 422 status code with a explanatory message is appropriate. However, if the plan change is failing due to internal reasons and the user should try again later, a 503 may be more appropriate.

Parameters

Name Type Description Example
heroku_id string The heroku_id field contains an identifier for the application that owns the add-on. The ID in the request URI (:provider_id) must be used to identify the add-on to manipulate, as heroku_id is not guaranteed to be unique. app1234@heroku.com
plan string the name of the plan to change to basic

Request Example

PUT /heroku/resources/:provider_id HTTP/1.1
Host: addon-slug.herokuapp.com
Authorization: Basic YWRkb24tc2x1ZzpzdXBlci1zZWNyZXQ=
Content-Type: application/json
Accept: application/json

{
  "heroku_id": "app1234@heroku.com",
  "plan": "basic"
}

Optional Parameters

Name Type Description Example
message string Further instructions to the user after changing the plan Resource has been updated and is available!

Response Example

HTTP/1.1 200 OK

{
  "message": "Resource has been updated and is available!"
}

Deprovision

When an add-on is removed from a user’s account, Heroku will make a DELETE request to your API.

Request Example

DELETE /heroku/resources/:provider_id HTTP/1.1
Host: addon-slug.herokuapp.com
Authorization: Basic YWRkb24tc2x1ZzpzdXBlci1zZWNyZXQ=
Content-Type: application/json
Accept: application/json

Response Example

HTTP/1.1 204 No Content

Feedback

Log in to submit feedback.