Linking with Orgs

Merit Apps can act on behalf of Orgs by asking Org Admins to "Link with" their App. Every Merit App has an App ID and an App Secret which are used to request a LinkAppUrl and obtain Org Access Tokens which can be used to authenticate requests on behalf of Merit Organizations.

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