Web Flow

In order for your App to work on behalf of third-party Orgs (ones other than your own Org), you'll need to utilize the Link with Merit web flow.

As you can see in the diagram below, the organization that owns the app permanently grants all permissions. If your application is only interacting with merits from your own organization, you can skip Link with Merit entirely! However, if you do require access to information from other organizations, you will need to request it from an admin of that organization using Link with Merit.

Your App may request some combination of the following permissions, please follow the principle of least privilege when requesting permissions from other orgs:

Permission Type	What it grants
CanEditOrg	Edit Org Details
CanManageAllMeritTemplates	Create and edit Merit Templates and Fields
CanSendAllMeritTemplates	Send and edit Merits
CanProposeAllMeritTemplates	Propose sending and editing Merits. Note, this permission does not grant access to view already sent merits.
CanManageOrg	All permissions are granted

> curl -X POST https://api.merits.com/v2/request_linkapp_url --user {appId}:{appSecret} -H "Content-Type: application/json" -d '{ "requestedPermissions": [{ "permissionType": "CanManageOrg" }], "successUrl": "/goodpath", "failureUrl": "/badpath", "state": "state" }'
{ "request_linkapp_url": "https://merits.com/link-app/?token=5aa5a3992bfa4e0006c47cdf", "expiration": "2019-01-31T18:48:51.000Z" }

Once you receive a request_linkapp_url from this endpoint, which will look like the following: https://merits.com/link-app?token={token}, re-direct your user to this special authorization page for your App.

Org ID Token

If a Merit Member chooses an Org to link your App with, they'll be redirected to your site along with a signed "Org ID Token" in a orgIdToken URL parameter. This token can be exchanged for an Org ID which in turn can be used to get an Org Access Token for the Organization, at which point you can begin making requests to the Merit API on behalf of the Organization!

To exchange an Org ID Token for an Org ID, just use the Org ID endpoint:

> curl https://api.merits.com/v2/org_id?org_id_token={orgIdToken} --user {appId}:{appSecret}
{ "orgId": "{orgId}" }

Once you have the Org ID, request your first Org Access Token:

> curl https://api.merits.com/v2/orgs/{orgId}/access --user {appId}:{appSecret}
{ "orgAccessToken": "{orgAccessToken}" }

And now you're ready to start making requests:

curl -H "Authorization: Bearer {orgAccessToken}" https://api.merits.com/v2/example/endpoint