Last updated July 14, 2025

Heroku AppLink provides an API to automate the creation, maintenance, and monitoring of connections, authorizations, and publications between a Salesforce org and a Heroku app.

Version Support

Heroku supports version 1 of the Heroku AppLink API. Heroku communicates certain changes made to the API, as well as any new API versions per our compatibility policy.

Authentication

The Heroku AppLink API requires a Heroku Platform API direct authorization token. This token is for your application’s Heroku user only. Heroku AppLink doesn’t support API access on behalf of other Heroku customers. The Heroku AppLink CLI plugin makes requests to the Heroku AppLink API with the default Bearer Token authentication scheme. The AppLink API determines if the user has access to the app and add-on associated with each request.

Make a request to Platform API to get the Add-on SSO Params endpoint with the add‑ons‑sso API schema variant:

GET /apps/:app_id/addons/:addon_id/ssoAuthorization: Bearer HRKU-01234567-89ab-cdef-0123-456789abcdefAccept: application/vnd.heroku+json; version=3.add-ons-sso

Request Methods

Most of the Heroku AppLink API responds to either GET, POST, PATCH, or DELETE requests.

Shared Objects

Org

This object represents a Salesforce or Data Cloud org.

User Auth

This object represents a Salesforce user’s details.

Connection Endpoints

Use these endpoints to create, get info, and maintain your AppLink connections.

Connect to an Org

Connect your AppLink add-on to a Salesforce or Data Cloud org.

POST /addons/${addon_uuid}/connections/[salesforce|datacloud]

Required Parameters

Optional Parameters

Example Request:

POST /addons/fe3b4938-3383-4c40-868c-1a5cdc38a358/connections/salesforce
{
  "connection_name": "productionOrg",
  "login_url": "https://login.salesforce.com"
}

Response Attributes

Example Response:

{
  "id": "a8bc7bcb-89c3-45c0-b7b7-4fb4427e598b",
  "redirect_uri": "https://login.salesforce.com/services/oauth2/authorize?client_id=3MVG...&redirect_uri=https%3A%2F%2Fcreds-virginia.events.staging.herokudev.com%2Fsalesforce%2Foauth%2Fcallback&response_type=code&state=ey...",
  "status": "connecting",
  "org": {
     "id": "00DSG00000DGEIr2AP",
     "connection_name": "productionOrg",
     "instance_url": "https://mydomain.my.salesforce.com",
     "type": "SalesforceOrg",
     "api_verion": "57.0",
     "user_auth": {
        "username": "admin@example.org",
        "user_id": "005...",
        "access_token": "00DSG00000DGEIr2AP!<token>"
      }
  "app_id": "ef01ec58-63f6-478b-ab87-34f82b3c5bdd",
  "addon_id": "fe3b4938-3383-4c40-868c-1a5cdc38a358",
  "created_at": "2025-04-06T18:20:42.226577Z",
  "connection_method": "OAuth"
  }
}

Connect to an Org with JWT

Connect your AppLink add-on to a Salesforce org with JWT.

POST /addons/${add_uuid}/connections/salesforce/jwt

Required Parameters

Optional Parameters

Example Request:

POST /addons/51fc983e-d106-4dac-8f75-9dd103d4381a/connections/salesforce/jwt
{
  "connection_name": "sandboxOrg",
  "login_url": "https://test.salesforce.com",
  "alias": "example-alias",
  "client_id": "3MVG8...NM0ZqZc9aT",
  "jwt_private_key": "-----BEGIN PRIVATE KEY-----\nMII...C+Q=\n-----END PRIVATE KEY-----",
    "username": "test-2mhpnyuxne8k@example.com"
}

Response Attributes

Example Response:

{
  "id": "a8bc7bcb-89c3-45c0-b7b7-4fb4427e598b",
  "status": "connecting",
  "org": {
    "id": "00DSG00000DGEIr2AP",
    "connection_name": "sandboxOrg",
    "instance_url": "https://mydomain.my.salesforce.com",
    "type": "SalesforceOrg",
    "api_verion": "57.0",
    "user_auth": {
        "username": "test-2mhpnyuxne8k@example.com"
        "user_id": "005...",
      "access_token": "00DSG00000DGEIr2AP!<token>"
    }
  },
  "app_id": "ba80caca-e1c6-41ee-9a60-39b7740e6865",
  "addon_id": "51fc983e-d106-4dac-8f75-9dd103d4381a",
  "created_at": "2025-04-06T18:20:42.226577Z",
  "connection_method": "JWT"
}

Disconnect from an Org

Disconnect your AppLink add-on from a Salesforce or Data Cloud org.

DELETE /addons/${addon_uuid}/connections/{conn_id_or_conn_name}

Required Parameters

Example Request:

DELETE /addons/fe3b4938-3383-4c40-868c-1a5cdc38a358/connections/productionOrg

Response Attributes

Example Response:

204 OK
{
  "id": "a8bc7bcb-89c3-45c0-b7b7-4fb4427e598b",
  "status": "disconnected"
}

Get Connections By Add-on

Get a list of AppLink connections for an add-on.

GET /addons/${addon_uuid}/connections

Required Parameters

Example Request:

GET /addons/fe3b4938-3383-4c40-868c-1a5cdc38a358/connections

Response Attributes

Example Response:

[
  {
     "id": "4f96e929-5e21-4f9e-8f3c-375186af31fc",
     "status": "connecting",
     "org": {
        "id": "00D000000000001AAA",
        "connection_name": "Original SF Org",
        "instance_url": "https://mydomain.my.salesforce.com",
        "type": "SalesforceOrg",
        "api_verion": "57.0",
        "user_auth": {
           "username": "user1@sf-org-1.com",
           "user_id": "005...",
           "access_token": "00DSG00000DGEIr2AP!<token>"
         }
       }
    "addon_id": "fe3b4938-3383-4c40-868c-1a5cdc38a358",
    "connection_method": "OAuth"
  },
  {
     "id": "aa216852-2294-4524-aea0-d633f36a6c36",
     "status": "disconnected",
     "org": {
        "id": "DCO000000000001CCC",
        "connection_name": "Test DC Org 1",
        "instance_url": "https://mydomain.my.salesforce.com",
        "type": "DatacloudOrg",
        "api_verion": "57.0",
        "user_auth": {
           "username": "user3@dc-org-1.com",
           "user_id": "005...",
           "access_token": "00DSG00000DGEIr2AP!<token>"
        }
     }
    "addon_id": "fe3b4938-3383-4c40-868c-1a5cdc38a358",
    "connection_method": "OAuth"
  },
  {
     "id": "bb155b7d-1eee-4fb1-900e-35421c07755e",
     "status": "connected",
     "org": {
        "id": "00D000000000002BBB",
        "connection_name": "Test SF Org 2"
        "instance_url": "https://mydomain2.my.salesforce.com",
        "type": "SalesforceOrg",
        "api_verion": "57.0",
        "user_auth": {
           "username": "user2@sf-org-2.com",
           "user_id": "005...",
           "access_token": "00DSG00000DGEIr2AP!<token>"
         }
     }
    "addon_id": "51fc983e-d106-4dac-8f75-9dd103d4381a",
    "connection_method": "JWT"
  }
]

Get Connections By App

Get a list of AppLink connections for an app.

GET /addons/${addon_uuid}/connections/${app_uuid}

Required Parameters

Example Request:

GET /addons/fe3b4938-3383-4c40-868c-1a5cdc38a358/connections/ef01ec58-63f6-478b-ab87-34f82b3c5bdd

Response Attributes

Example Response:

[
  {
    "id": "4f9dff98-11e9-4b0f-9f2e-bbb710bf56fa",
    "status": "connected",
    "org": {
      "id": "00DSG00000KWTOr2AP",
      "connection_name": "myOtherOrg",
      "instance_url": "https://mydomain.my.salesforce.com",
      "type": "SalesforceOrg",
      "api_verion": "57.0",
      "user_auth": {
        "username": "use@however.org"
        "user_id": "005...",
    "access_token": "00DSG00000DGEIr2AP!<token>"
    }
   },
    "app_id": "ef01ec58-63f6-478b-ab87-34f82b3c5bdd",
    "addon_id": "fe3b4938-3383-4c40-868c-1a5cdc38a358",
    "created_at": "2025-04-06T18:20:42.226577Z",
    "last_modified_at": "2025-04-09T18:20:42.226577Z",
    "connection_method": "OAuth",
  },
  {
    "id": "ce2ffad8-5692-40e5-b1f6-7f7206d3d5ef",
    "status": "connected",
    "org": {
      "id": "00DSG00000DGEIr2AP",
      "connection_name": "productionOrg",
      "instance_url": "https://mydomain.my.salesforce.com",
      "type": "SalesforceOrg",
      "api_verion": "57.0",
      "user_auth": {
        "username": "admin@example.org"
        "user_id": "005...",
    "access_token": "00DSG00000DGEIr2AP!<token>"
    }
   },
    "app_id": "ef01ec58-63f6-478b-ab87-34f82b3c5bdd",
    "addon_id": "fe3b4938-3383-4c40-868c-1a5cdc38a358",
    "created_at": "2025-04-06T18:20:42.226577Z",
    "last_modified_at": "2025-04-09T18:20:42.226577Z",
    "connection_method": "OAuth",
  }
]

Get Connection Details

Get info for an individual Heroku AppLink connection.

GET /addons/${addon_uuid}/connections/{conn_id_or_conn_name_or_org_id}

Required Parameters

Example Request:

# Request using connection name
GET /addons/fe3b4938-3383-4c40-868c-1a5cdc38a358/connections/productionOrg

# Request using connection UUID
GET /addons/fe3b4938-3383-4c40-868c-1a5cdc38a358/connections/a8bc7bcb-89c3-45c0-b7b7-4fb4427e598b

# Request using Org ID
GET /addons/fe3b4938-3383-4c40-868c-1a5cdc38a358/connections/00DSG00000DGEIr2AP

Response Attributes

Example Response:

{
  "id": "a8bc7bcb-89c3-45c0-b7b7-4fb4427e598b",
  "status": "connected",
  "org": {
    "id": "00DSG00000DGEIr2AP",
    "connection_name": "productionOrg",
    "instance_url": "https://mydomain.my.salesforce.com",
    "type": "DataCloudOrg",
    "api_verion": "57.0",
      "user_auth": {
        "username": "admin@example.org"
        "user_id": "005...",
    "access_token": "00DSG00000DGEIr2AP!<token>"
    }
  },
  "app_id": "ef01ec58-63f6-478b-ab87-34f82b3c5bdd",
  "addon_id": "fe3b4938-3383-4c40-868c-1a5cdc38a358",
  "created_at": "2025-04-06T18:20:42.226577Z",
  "created_by": "creator@somewhere.com",
  "last_modified_at": "2025-04-09T18:20:42.226577Z",
  "last_modified_by": "modifier@somewhere.com",
  "created_via_app": "Foo"
  "connection_method": "OAuth"
}

Authorization Endpoints

Use these endpoints to create, get info, and maintain your AppLink authorizations.

Authorize a User

Authorize a Salesforce or Data Cloud user and store their credentials to your AppLink add-on.

POST /addons/${addon_uuid}/authorizations/[salesforce|datacloud]

Required Parameters

Optional Parameters

Example Request:

POST /addons/fe3b4938-3383-4c40-868c-1a5cdc38a358/authorizations
{
  "developer_name": "authUser",
  "login_url": "https://login.salesforce.com"
}

Response Attributes

Example Response:

{
  "id": "a8bc7bcb-89c3-45c0-b7b7-4fb4427e598b",
  "redirect_uri":   "https://login.salesforce.com/services/oauth2/authorize?client_id=3MVG...&redirect_uri=https%3A%2F%2Fcreds-virginia.events.staging.herokudev.com%2Fsalesforce%2Foauth%2Fcallback&response_type=code&state=ey...",
  "status": "authorizing",
  "org": {
    "id": "00DSG00000DGEIr2AP",
    "developer_name": "productionOrg",
    "instance_url": "https://mydomain.my.salesforce.com",
    "type": "SalesforceOrg",
    "api_verion": "57.0",
      "user_auth": {
        "username": "admin@example.org"
        "user_id": "005...",
      "access_token": "00DSG00000DGEIr2AP!<token>"
    }
  },
  "created_at": "2025-04-06T18:20:42.226577Z",
}

Remove User Authorization

Remove an existing Salesforce or Data Cloud user authorization on your AppLink add-on.

DELETE  /addons/${addon_uuid}/authorizations/${developer_name_or_id}

Required Parameters

Example Request:

GET /addons/fe3b4938-3383-4c40-868c-1a5cdc38a358/authorizations/authUser

Response Attributes

Example Response:

204 OK
{
  "id": "a8bc7bcb-89c3-45c0-b7b7-4fb4427e598b",
  "status": "disconnected"
}

Get Authorized Users

Get a list of AppLink authorized users for an add-on.

GET /addons/${addon_uuid}/authorizations

Required Parameters

Example Request:

GET /addons/fe3b4938-3383-4c40-868c-1a5cdc38a358/authorizations

Response Attributes

Example Response:

[
 {
  "id": "a8bc7bcb-89c3-45c0-b7b7-4fb4427e598b",
  "status": "authorizing",
  "org": {
       "id": "00DSG00000DGEIr2AP",
    "developer_name": "productionOrg",
    "instance_url": "https://mydomain.my.salesforce.com",
    "type": "SalesforceOrg",
       "api_verion": "57.0",
       "user_auth": {
        "username": "admin@example.org"
        "user_id": "005...",
    "access_token": "00DSG00000DGEIr2AP!<token>"
    }
  },
  "created_at": "2025-04-06T18:20:42.226577Z",
  "created_by": "foo@heroku.com",
  "last_modified_at": "2025-04-09T18:20:42.226577Z",
  "last_modified_by": "bar@heroku.com"
},
{
  "id": "b8bc7bcb-89c3-45c0-b7b7-4fb4427e598a",
  "status": "authorized",
  "org": {
       "id": "00DSG00000DGEIr2AP",
       "developer_name": "productionOrg2",
       "instance_url": "https://mydomain.my.salesforce.com",
       "type": "SalesforceOrg",
       "api_verion": "57.0",
       "user_auth": {
         "username": "admin@example.org"
         "user_id": "005...",
     "access_token": "00DSG00000DGEIr2AP!<token>"
    }
  },
  "created_at": "2025-03-06T18:20:42.226577Z",
  "created_by": "foo@heroku.com",
  "last_modified_at": "2025-03-09T18:20:42.226577Z",
  "last_modified_by": "bar@heroku.com"
}
]

Get Authorization Details

Get info for an individual authorized user.

GET /addons/${addon_uuid}/authorizations/${developer_name_or_id}

Required Parameters

Example Request:

GET /addons/fe3b4938-3383-4c40-868c-1a5cdc38a358/authorizations/productionOrg

Response Attributes

Example Response:

{
  "id": "b8bc7bcb-89c3-45c0-b7b7-4fb4427e598a",
  "status": "authorized",
  "org": {
       "id": "00DSG00000DGEIr2AP",
       "developer_name": "productionOrg2",
       "instance_url": "https://dmomain.my.salesforce.com",
       "type": "SalesforceOrg",
       "api_verion": "57.0",
       "user_auth": {
          "username": "admin@example.org",
          "user_id": "005...",
      "access_token": "00DSG00000DGEIr2AP!<token>"
   }
  },
  "created_at": "2025-03-06T18:20:42.226577Z",
  "last_modified_at": "2025-03-09T18:20:42.226577Z",
  "created_by": "foo@heroku.com",
  "last_modified_by": "foo@heroku.com",
  "created_via_app": "Foo"
}

Publication Endpoints

Use these endpoints to publish apps, get info, and maintain your AppLink publications.

Publish Your App to Salesforce

Publish your app to Salesforce and turn your app’s APIs into actions.

POST /addons/${addon_uuid}/connections/salesforce/${conn_id_or_conn_name}/apps

Required Parameters

app_request

Example Request:

POST /addons/fe3b4938-3383-4c40-868c-1a5cdc38a358/connections/salesforce/my-prod-org/apps

content-type: application/json
  "app_request" {
    "client_name": "foo"
     "authorization_connected_app_name": "connected-app"
     "authorization_permission_set_name" "permission-set"
  }

content-type: application/zip
  "metadata": <binary-encoded metadata.zip>
}

Response Attributes

Example Response:

{
  "id": "valid-heroku-esr-id"
}

Get Publications By Connection

Get a list of AppLink publications for a connection.

GET /addons/${addon_uuid}/connections/salesforce/${conn_id_or_conn_name}/apps

Required Parameters

Example Request:

GET /addons/fe3b4938-3383-4c40-868c-1a5cdc38a358/connections/salesforce/my-prod-org/apps

Response Attributes

Example Response:

[
  {
    "app_id": "1c6bb699-2a91-47b3-b55e-8f2e37254684",
    "heroku_app_link_id": "1up000000000000",
    "external_service_id": "0Lexx0000004H77CAE",
    "external_service_name": "MyApp",
    "connection_name": "my-prod-org",
    "org_id": "00DSG00000DGEIr2AP",
    "app_name": "app-name",
    "created_at": "2025-04-06T18:20:42.226577Z",
    "created_by": "creator@somewhere.com",
    "last_modified_at": "2025-04-09T18:20:42.226577Z",
    "last_modified_by": "modifier@somewhere.com",
  }
]

Get Publications by App

Get a list of AppLink publications for an app.

GET /addons/${addon_uuid}/connections/salesforce/${conn_id_or_conn_name}/apps/${app_uuid}

Required Parameters

Example Request:

GET /addons/fe3b4938-3383-4c40-868c-1a5cdc38a358/connections/salesforce/my-prod-org/apps/1c6bb699-2a91-47b3-b55e-8f2e37254684

Response Attributes

Example Response:

[
  {
    "app_id": "1c6bb699-2a91-47b3-b55e-8f2e37254684",
    "heroku_app_link_id": "1up000000000000",
    "external_service_id": "0Lexx0000004H77CAE",
    "external_service_name": "MyApp",
    "connection_name": "my-prod-org",
    "org_id": "00DSG00000DGEIr2AP",
    "app_name": "app-name",
    "created_at": "2025-04-06T18:20:42.226577Z",
    "created_by": "creator@somewhere.com",
    "last_modified_at": "2025-04-09T18:20:42.226577Z",
    "last_modified_by": "modifier@somewhere.com",
  }
]

Delete Publications

Delete an AppLink publication.

DELETE /addons/${add_on_id_or_name}/connections/salesforce/${conn_id_or_conn_name}/apps/{app_uuid}

Required Parameters

Example Request:

DELETE /addons/fe3b4938-3383-4c40-868c-1a5cdc38a358/connections/salesforce/my-prod-org/apps/1c6bb699-2a91-47b3-b55e-8f2e37254684

Example Response:

200 OK

Data Cloud Endpoints

Use these endpoints to create, get info, and maintain your Data Action Targets.

Create a Data Action Target

Create a Data Cloud Data Action Target on your AppLink add-on.

POST /addons/${addon_uuid}/connections/datacloud/conn_id_or_conn_name_or_org_id/data_action_targets

Required Parameters

Optional Parameters

Example Request:

POST /addons/fe3b4938-3383-4c40-868c-1a5cdc38a358/connections/datacloud/productionOrg/data_action_targets

{
  "type": "Webhook",
  "label": "Customer Update Webhook",
  "api_name": "customer_update_webhook",
  "target_endpoint": "/webhooks/customer-update"
}

Response Attributes

Example Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "Webhook",
  "label": "My Webhook Target",
  "api_name": "my_webhook_target",
  "state": "Created",
  "target_endpoint": "/webhooks/my_webhook_target",
  "connection_id": "123e4567-e89b-12d3-a456-426614174000",
  "app_id": "456e7890-e89b-12d3-a456-426614174001"
}

Get Data Action Target Details

Get info on a Data Action Target.

GET /addons/${addon_uuid}/connections/datacloud/conn_id_or_conn_name_or_org_id/data_action_targets/{id_or_api_name}

Required Parameters

Example Request:

GET /addons/fe3b4938-3383-4c40-868c-1a5cdc38a358/connections/datacloud/productionOrg/data_action_targets/customer_update_webhook

Response Attributes

Example Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "Webhook",
  "label": "My Webhook Target",
  "api_name": "my_webhook_target",
  "state": "Created",
  "target_endpoint": "/webhooks/my_webhook_target",
  "connection_id": "123e4567-e89b-12d3-a456-426614174000",
  "app_id": "456e7890-e89b-12d3-a456-426614174001"
}