App installation process

During a user's installation of your app, you can use your app manifest to hook into this process.

Note these are all optional.

Hook url

By adding a hook_url to your app manifest, a webhook POST will be sent to that url every time a user installs your app. Here's an example payload:

{
  "event":{
    "type":"app.installed",
    "payload":{
      "app":{
        "id": "<your app id>"
      },
      "user":{
        "username":"[email protected]",
        "email":"[email protected]",
        "organizationDomain": "example.com"
      },
      "installed_at":"2021-05-12T12:50:43.743Z"
    }
  }
}

Beware different event types might be introduced in the future, so in order to receive app installations, you should always validate the event type is exactly "app.installed".

Note that webhook payloads follow our Backwards Compatibility policy similarly to API response schemas, this means we'll preserve properties listed above, but additional ones might be added in the future.

Install url

Some apps require a user to provide during installation some settings, secrets, or grant access to an external account. You can do this by specifying an install_url in your app manifest.

This is optional, and not recommended unless required for your app to function.

When doing so, every time a user installs your app, the browser will be redirect to the install_url, including an installation id in the query string. You can use this page to perform any intermediate step like:

show the user form to enter any required settings
ask the user for an API key to access another service
ask the user to authenticate and grant access to another service (eg. an OAuth2 flow or any similar method)

Finally, in order to complete installation, the browser must POST back to this url: https://platform-api.securityscorecard.io/apps/installation-data, including in the body as form fields the installation id (sent in the query string) and any additional secrets to store for this user.

When your app requires any secrets to complete the installation, they must be declared in the app manifest too. This will allow our platform to detect if the app installation is complete, or if a re-install is required.

{
  ...
  // will send users to a url like https://example.com/your-app/install?installation=<installation id>
  "install_url": "install",
  "secrets": [
    {
      "key": "ACCESS_TOKEN",
      "description": "a secret access token",
      "value_required": true
    }
  ],
}

These secrets are encrypted at rest, and only transferred using https.

When an Action in your app is invoked, these secrets are sent in an x-ssc-app-secrets http header, as a JSON object.