Accessing API in behalf of the app user

Your app might need to access the SecurityScorecard API in behalf of the user installing it. This can be used to fetch data from scorecards, manipulate portfolios, and other actions described in Core Resources.

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

You can ask users to authorize your app access specific API scopes by adding the auth section to your app manifest:

{
  ...
  "auth": {
    "redirect_uri": "https://example.com/my-app/oauth",
    "scopes": [
      // an example of all available scopes, remember to only include the minimum neeeded
      "issue:summary",
      "user:read",
      "users:list",
      "invite:create",
      "portfolio:read",
      "portfolio:edit",
      "score:summary",
      "issue:summary",
      "issue:details",
      "issue:refute",
      "history:score",
      "report:create",
      "report:read",
      "rule:edit"
    ]
  },
}

This will allow your app to obtain an API token using a typical OAuth2 code flow.

During installation, users will be redirected to your redirect_uri including a secret one-time code in the query string. You can use that code together with:

your app client_id, this is simply your app id as it can be seen on the url of your app in the marketplace.
your app client_secret, this can be obtained at https://api.securityscorecard.io/apps/:id/secret (authenticating as the creator of the app). You can use a POST to this same url to generate a new one.

to obtain a API token using this endpoint from your backend:

curl -X POST \
  https://api.securityscorecard.io/apps/authorize/tokens \
  -H 'content-type: application/json'
  --data '{"client_id":"<your app id>","client_secret":"<your app secret>","code":"the one-time code received"}'

These tokens will be valid until revoked which happens if:

the user uninstalls the app
the user re-installs generating a new token
the user is deleted or their account is disabled

Initiating the authorization flow from a different website

You can start the authorization from a different website by opening a popup with a url like this:

https://platform.securityscorecard.io/#/marketplace/<your app id>/authorize?state=<optional state that will forwarded to your redirect_uri>&redirect_uri=<your app redirect_uri or any subpath of it>&popup=true

This popup will ask the user to sign in with a SecurityScorecard account (unless already logged in), and allow your app to access the specified scopes. If approved, the user will be redirected to the specified redirect_uri as described above.

Adding additional scopes

You should always require the minimum scopes required by your app to function. If your app requires additional scopes in the future, they can be added to your manifest. From this moment new users will grant the new scopes, and existing users will need to re-install.