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 athttps://api.securityscorecard.io/apps/:id/secret
(authenticating as the creator of the app). You can use aPOST
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.
Updated almost 3 years ago