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: * The app is registered in MerusCase (either in-app using a MerusCase account, or through the API). * Each user authorizes the app to access their data. A unique Bearer Token is created for each authorized user. * 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 info@meruscase.com 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 hello@example.com \
-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 info@meruscase.com 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:

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:

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

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.

  1. 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.