Every Merit App has an App ID and an App Secret which are used to obtain Org Access Tokens which can be used to authenticate requests on behalf of Merit Orgs.

Once you have your App Key and App Secret you're good to go. However, on its own an App isn't able to very much. On the Merit Platform, an App must get permission from either an Organization or a Member to be able to take action. When creating an App, your Org is the first to give permission, or "Link with Org". Follow the steps below to properly authenticate your API calls, if you didn't get your appId & appSecret yet, follow the checklist in the Quick Start .



If your App Secret ever becomes public please reach out to [email protected] for help deactivating and replacing it.

Acting on Behalf of Third-Party Organizations

As mentioned above, in order for your App to act on behalf of third-party Organizations (ones other than your own), you'll need to ask Merit Org Admins to "link" their Org to your App. You can learn how to do that in our Linking with Orgs Guide.

Access Member Profiles and Merits

In order for your App to access Merit Members' Merits and profiles on behalf of an Organization you'll need to ask them to "Login with Merit". You can learn how to do that in our Login with Merit guide.

API Key - Basic Authentication as your App

Every App has an API Key formed by base-64 encoding the concatenation of your App ID, ":", and your App Secret. This basic key is only used for obtaining more specific access tokens, such as requesting a Link App URL or obtaining an orgAccessToken.

apiKey = base64(appId + ":" + appSecret)

To authenticate your requests as an App, send an Authentication header with the concatenation of the word "Basic", a space, and your API key:

curl -H "Authorization: Basic {apiKey}"

The popular cURL tool has built-in support for Basic HTTP authentication, handling the "Basic " prefix and base-64 encoding for you.

curl --user {appId}:{appSecret}

Authenticating on Behalf of an Organization

Almost all requests to the Merit API are done on behalf of a specific Organization rather than a general App.

Apps can always make requests on behalf of the Organization that created them. They can also authenticate on behalf of other Organizations that have granted the App special permissions by "Linking" with the App.

To authenticate on behalf of an Organization, the App must request a short-lived Org Access Token.

> curl -X POST --user {appId}:{appSecret}{orgId}/access
{ "orgAccessToken": "{orgAccessToken}" }

Next, the App can make requests on behalf of the Organization using the Org Access Token as a "bearer" token:

curl -H "Authorization: Bearer {orgAccessToken}"