Rutter Link

The Basics

Rutter Link is the client-side component that your users will interact with in order to link their accounts to Rutter and allow you to access their accounts via the Rutter API.

Rutter Link will handle credential validation, OAuth, and error handling for each platform that we support. Link works across all modern browsers and platforms, including web, iOS, Android, and mobile webviews.

Web

On web instances React & Javascript, loading the Rutter JS will create a global Rutter object on the window object. To open the Merchant Auth flow, you must call Rutter.create() while passing in your public_key, and then open() on the resulting object.

Create

The create function takes in an object as an argument. Below is an example:

1
const rutterInstance = Rutter.create({
2
publicKey: "YOUR_RUTTER_PUBLIC_KEY",
3
onSuccess: function (publicToken) {
4
// Send publicToken to your backend and exchange
5
console.log("public token: " + publicToken)
6
},
7
onError: function (error) {
8
console.error(error)
9
}
10
})

After the Rutter Instance is created, the resulting object has the following functions:

Open

The open function opens the Merchant Auth popup, and will return a publicToken after a successful authentication to the callback you specified in the create function above. Below is an example:

1
// Assuming rutterInstance has already been created as shown above
2
3
// Opens the Rutter popup
4
rutterInstance.open()
5
6
// Opens the Rutter popup directly to the Shopify Auth Step
7
rutterInstance.open({
8
platform: "SHOPIFY"
9
})

Troubleshooting

You should set your Cross-Origin-Opener-Policy policy to be same-origin-allow-popups or Rutter Link will fail to communicate with your application. The reason for this is that Rutter Link uses the window.postMessage() method to communicate between the popup and the parent window.

You can use the debug mode to see what's going on under the hood. To enable debug mode, set the debug property to true when creating instantiating Rutter Link.

Source Code

The source code for Rutter Link Base is available on Github. This is the code that's used to generate the Rutter Link Javascript and React libraries. It is responsible for communication between the parent window and the popup.

Token Exchange

Rutter makes it easy for you to obtain and manage tokens from Rutter Link. A public_token is returned whenever a merchant successfully shares their data with you. However, the public_token cannot be used directly with our API, it must be exchanged for an access_token through our Token Exchange endpoint.

Token Exchange Flow

  1. Merchant authorizes you to use their data via Rutter Link.
  2. Link returns a public_token on the frontend, which must be exchanged for an access_token.
  3. Exchange the public_token for an access_token by calling /item/public_token/exchange.

The access_token can then be used to call Rutter endpoints and obtain information about a Connection.

Configuration

JavaScript and React bindings take in a configuration object with the following format:

FieldTypeNotes
publicKeystringYour Rutter-issued public token which you can find in the Rutter Dashboard.
onSuccessfunction of following type: (publicToken?: string) => any;The publicToken query parameter is the public token of a Rutter Connection. You will need to exchange this for an access_token to use the API.
onExitfunction of following type: (err?: ErrorEnum) => any;See definition for ErrorEnum below
debugbooleanWhether to enable debug mode, which log the steps of the Rutter Link flow to the console. Defaults to false.

A Note on Callbacks

Only one callback will be called - either onSuccess or onExit, but not both.

ErrorEnum

ValueConditions to Trigger
"MERCHANT_CLOSED"The popup window has been closed prematurely (usually by the user) - i.e. authentication is incomplete but window is closed.
"UNKNOWN_ERROR"The window has passed an event to the link bindings which cannot be handled.

Quickstarts