Login with Merit
Merit Apps can ask Merit Members for programmatic access to their merits and profile on behalf of an Organization by asking them to "Login with Merit" using your App.
Web Flow
In order for your App to see a Merit Member's profile or Merits you'll need to obtain permission directly from that member by utilizing the "Login with Merit" web flow.
As you can see in the below diagram, apps on merit request permissions on behalf of a Merit Organization, not the app itself. Because of this, your app will need to first need to link with an organization using the Link with Merit authorization flow.
The Login with Merit endpoint will require authorization with an orgAccessToken that your app has generated with another Merit Organization. It is possible for your app to request these permissions on behalf of your own organization, however it is required that the member's permission be requested for the specific organization that your app is sharing the member's data with.
The RequestLoginWithMerit Url endpoint is [documented here] (https://developer.merits.com/reference#request-login-with-merit-url)
Your App may request some combination of the following permissions in the table
| Permission Type | What it grants |
|---|---|
| CanViewAllStandardMerits | View Merits sent to the recipient by any Org |
| CanViewPublicProfile | View the recipient's name and primary email |
| CanViewAllStandardMeritsFromOrg (with a specific OrgId) | View Merits sent to the recipient by a specific Org NOTE: it is not necessary to pass this permission for your own Org or the linked Org; Those are given |
curl -X POST -H "Authorization: Bearer {orgAccessToken}" https://api.merits.com/v2/orgs/5bb5a3992bfa430006c47bd5/request_loginwithmerit_url -H "Content-Type: application/json" -d '{ "requestedPermissions": [{ "permissionType": "CanViewPublicProfile" }, { "permissionType": "CanViewAllStandardMerits" }], "successUrl": "/goodpath", "failureUrl": "/badpath", "state": "somestatevariable" }'
Once you receive a request_loginwithmerit_url from this endpoint, which will look like the following: https://merits.com/login-with-merit?token={token}, re-direct your user to this special authorization page for your App.
If a Merit Member agrees to Login with Merit for a given App and Org, they'll be sent a pre-accepted Merit Access Merit for the App from the Org (as shown in the diagram above.
Obtaining the Member ID
Once the Login with Merit flow is completed, the member is then redirected to your site along with a Merit Member ID Token in the
memberIdTokenURL parameter. You can exchange this token for a `Member ID using the Member ID Token endpoint.
As long as their Merit Access Merit remains accepted your App will be granted special permissions to access the Member's merits and profile. You'll probably want to start by fetching their merits using the Member merits endpoint.
Updated almost 4 years ago