App Setup and Authentication

Overview

If you are interested in a partnership with MerusCase (i.e. providing your services to multiple firms), follow the First Steps for Partners instructions below. This partnership agreement is not required for developers looking to integrate with only one firm or user. Developers working with a single firm or user should follow the First Steps for Individual Developers instructions.

Here is a summary of the app setup and authentication process:

  1. The app is registered in MerusCase (either in-app using a MerusCase account, or through the API).
  2. Each user authorizes the app to access their data. A unique Bearer Token is created for each authorized user.
  3. The unique Bearer Token is used in the header of each request on behalf of that user.

First Steps for Partners

If you are interested in forming a Partnership with Merus to provide your services to many MerusCase users from different firms, please reach out to us by emailing [email protected] to get started. Once a Partnership has been formed, you’ll have access to our API and be able to create your App in MerusCase. Once complete, your app can be included in each firm globally, or can be published in the MerusCase App Store for use by each MerusCase firm.

First Steps for Single-Firm Developers

If you are a developer working with a single firm or user, you do not need to set up an official partnership with MerusCase. For ease of use, most app setup and authentication can be done within the MerusCase application. It is recommended that you follow the instructions below to register the app within MerusCase and Authorize Users from the 3rd Party Apps page.

Registering a New App in Merus

API consumers must register an app in order to initiate OAuth sessions and act on behalf of a user.

Apps may be registered in two ways:

OR

Registering a 3rd Party App through the MerusCase API

Request

POST https://api.meruscase.com/oauthApps/add

Parameters

Name Type Description
redirect_uri string Required The app’s callback URL.
name string Required The application’s display name.

Examples: cUrl

curl -u [email protected] \
-d data[OauthApp][name]="Hello World" \
-d data[OauthApp][redirect_uri]=https://example.com/auth/merus/callback \
https://api.meruscase.com/oauthApps/add \
JavaScript Example Forthcoming

Registering a 3rd Party App Within MerusCase, using a Merus Vendor account

You can also register an App in MerusCase using your vendor login credentials.

  1. After logging into MerusCase, go to Tools & Settings in the top menu of MerusCase, and select 3rd Party Apps.

  1. To register a new App, select App Publisher then click on the New App button.

  2. Fill in the requested information (please refer to the notes on the redirect_uri in the Authentication section), and click Save.

Once your app is created in MerusCase and you have a current Partnership Agreement with MerusCase, you may email [email protected] to have your app published in the App Store, which will allow MerusCase users to provide authentication for your app.

Authenticating Users via Oauth

The Merus API uses OAuth 2.0 to provide third party apps with access to users’ accounts without directly requiring their password. Each request through the API will use a user-specific Bearer Token to authorize access to the user’s data.

The general OAuth 2.0 flow in MerusCase works as follows:

  1. The app is created and is assigned an id and a secret key (client_secret).
  2. The app requests authentication from the user, and the user in turn authenticates the application. This generates the authorization code, which is stored at the redirect URI.
  3. The authorization code is exchanged for a secure Bearer Token.
  4. The Bearer Token is used on every request made through the API on behalf of that user.

MerusCase can handle the OAuth flow for you, and store your client secret and bearer tokens. This is provided for convenience, but is less secure than independently managing the authorization information. If MerusCase is managing the OAuth flow for your application, the flow works as follows:

  1. The app is created and is assigned an id and a secret key (client_secret).
  2. The app requests authentication from the user, and the user in turn authenticates the application. The authorization code is stored in MerusCase, and our system exchanges the code for a Bearer Token automatically.
  3. The Bearer Token is made available in MerusCase, and is used on every request made through the API on behalf of that user.

The OAuth 2.0 flow is handled as listed above if the redirect_uri for the app is https://api.meruscase.com/oauth/authcodeCallback

Understanding Authentication tokens

Authentication bearer tokens, when sent in the headers of a request, should be used with the proper name:value syntax. In Postman, ‘Authorization’ should be entered into the key field while ‘Bearer {bearer token}’ should be entered into the value field. Put together, the proper syntax is ‘Authorization : Bearer {bearer token}.’

If you’re using something other than Postman, such as Python and the requests library, the proper syntax for your header would be: header={‘Authorization’ : ‘Bearer [bearer token]’}, replacing the [bearer token] with your own token.

Authentication through the API

Accessing most endpoints requires an OAuth access token. In order to use OAuth, you must register an app with the API. This will provide an app_id and key, which can be used to authenticate users.

*** The OAuth requests outlined below are provided for testing and diagnostic purposes, but user authentication is primarily handled through the MerusCase App Store. ***

  1. Redirect users to request access:

    Request

    GET https://api.meruscase.com/oauth/authorize

    Parameters

    Name Type Description
    client_id integer Required The app’s id.
    redirect_uri string Required The app’s callback URL.
    response_type string Required The OAuth2 response type. Currently only code is supported.

    cUrl Example Forthcoming
    JavaScript Example Forthcoming

    This will return an Authorization Code for the user

  2. Exchange the Authorization Code for an access token

    After the user has authorized the application, they will be redirected to the redirect_uri, with a code param. This param can be exchanged for an access token:

    Request

    POST https://api.meruscase.com/oauth/token

    Parameters

    Name Type Description
    client_id integer Required The app’s id.
    client_secret string Required The app’s secret key.
    code string Required The OAuth2 access code received after a successful authorization.

    cUrl Example Forthcoming
    JavaScript Example Forthcoming

    NOTE: This step is not necessary if MerusCase is handling your app’s OAuth flow.

MerusCase Authentication

MerusCase handles authentication for you from within 3rd Party Apps. Once your app has been registered and published, Merus users will be able to authorize your App under the My Apps section of 3rd Party Apps.

  1. The MerusCase End User will need to navigate to Tools & Settings in the top menu of MerusCase, and select 3rd Party Apps.

  2. In the My Apps tab of 3rd Party Apps, the end user will need to locate the vendor’s published App, and click on it to open the right panel.

  3. When the end user clicks Allow this App to Access My Firm, they will be redirected to the Authentication Page, which will ask them for their credentials, then ask them to confirm their authorization. Clicking Yep will generate a token which will allow you to access any information in Merus which they’re able to view.

A token generated in Merus can be revoked by the user who provided the authorization, or by a firm administrator. You can view all end users who have authorized your App at any point in the App Publisher tab of 3rd Party Apps.

Click the control column for your App and select App Users to see this list of users.

Additionally, you may view their token by clicking the control column next to their name in the right panel and selecting Display Token.

Basic Auth

The API can also be accessed with HTTP basic auth, using a user’s credentials. This is provided for scripting and debugging purposes.

Third party applications must not ask for or collect Merus credentials. Users should be directed through the OAuth flow.