JavaScript Quickstart

Getting started with Rutter

In this guide, we'll go through the steps necessary to add Rutter to any JavaScript app. If you don't use JavaScript, see the React Quickstart.

📘

Rutter is also easily installable via vanilla JavaScript.

You can use this recipe to see a working example.

Here are the main steps:

  1. Setup Rutter Link in your frontend
  2. Exchange a public_token for an access_token from Rutter in your backend
  3. Make requests to Rutter's API with your access_token

Install Rutter Link

First, we'll need to setup Rutter Link in your frontend. Rutter Link handles the heavy-lifting of allowing a merchant to share data with your app.

Add the following script tag to your website / front-end.

<script src="https://unpkg.com/@rutter/[email protected]" type="text/javascript"></script>

This script injects a global Rutter variable on the window object.

Open the Rutter popup

Then, on any HTML component click handler or event, you can open the Rutter Link authentication popup by instantiating a Rutter object with Rutter.create and then calling .open.

<!DOCTYPE html>
<html>
  <head>
    <script src="https://unpkg.com/@rutter/[email protected]" type="text/javascript"></script>
    <script>
    function loadRutter() {
      var rutterInstance = Rutter.create({
        publicKey: "YOUR_RUTTER_PUBLIC_KEY",
        onSuccess: function (publicToken) {
          // Send publicToken to your backend and exchange
          // https://docs.rutterapi.com/reference#exchange-tokens
          console.log("public token: " + publicToken)
        }
      })
      rutterInstance.open();
  }
    </script>
  </head>
    <body>
    <p><button onclick="loadRutter()">Load Rutter!</button></p>
    </body>
</html>

After the merchant clicks the button, the Rutter Link popup will appear and will allow the merchant to share their data with you. At the end, you will receive a publicToken, signifying a successful connection with the merchant's store.

You can also pre-supply a platform enum in Rutter Link to direct the merchant through a specific platform authentication.

<!DOCTYPE html>
<html>
  <head>
    <script src="https://unpkg.com/@rutter/[email protected]" type="text/javascript"></script>
    <script>
    function loadRutter() {
      var rutterInstance = Rutter.create({
        publicKey: "YOUR_RUTTER_PUBLIC_KEY",
        onSuccess: function (publicToken) {
          // Send publicToken to your backend and exchange
          // https://docs.rutterapi.com/reference#exchange-tokens
          console.log("public token: " + publicToken)
        }
      })
      rutterInstance.open({ platform: "SHOPIFY" });
  }
    </script>
  </head>
    <body>
    <p><button onclick="loadRutter()">Load Rutter!</button></p>
    </body>
</html>

Exchange public_token for access_token

However, for security reasons, the publicToken cannot be used to access the Rutter API directly. The publicToken must be exchanged for an access_token using the Exchange Tokens endpoint.

We'll need to pass the public_token to our backend, exchange it for an access_token, and then we can start accessing data. Let's modify the frontend code a bit:

<!DOCTYPE html>
<html>
  <head>
    <script src="https://unpkg.com/@rutter/[email protected]" type="text/javascript"></script>
    <script>
    function loadRutter() {
      var rutterInstance = Rutter.create({
        publicKey: "YOUR_RUTTER_PUBLIC_KEY",
        onSuccess: function (publicToken) {
          // Send publicToken to your backend and exchange
          // https://docs.rutterapi.com/reference#exchange-tokens
          callBackendAPI(publicToken)
        }
      })
      rutterInstance.open();
  }
    </script>
  </head>
    <body>
    <p><button onclick="loadRutter()">Load Rutter!</button></p>
    </body>
</html>

We assume that callBackendAPI hits one of your backend endpoints.

Now, let's write a function on the backend that takes the publicToken and exchanges it for an access_token. To do this you can use your favorite HTTP request library. Here, we use Axios.

const axios = require('axios');

async function backendHandler(publicToken, userId) {
  const res = await axios.post("https://sandbox.rutterapi.com/item/public_token/exchange",
  {
    client_id: "YOUR_RUTTER_CLIENT_ID",
    secret: "YOUR_RUTTER_SECRET",
    public_token: publicToken
  })
 const access_token = res.data.access_token;
 // Save the access_token and associated userId in your DB 
 saveAccessTokenForUser(access_token, userId);
}

The snippet above exchanges a publicToken for an access_token, and saves the access_token for the corresponding user. Now, you can fetch data for this user at any time by retrieving the access_token in your database, and calling the Rutter API.

Make your first API call

Now, let's make a request to the Fetch All Orders endpoint:

axios.get("https://sandbox.rutterapi.com/orders", {
 params: {
   access_token: "RUTTER_ACCESS_TOKEN",
   limit: 1
 },
 auth: {
   username: "RUTTER_CLIENT_ID",
   password: "RUTTER_SECRET"
 }
})

Rutter uses HTTP Basic Authentication to verify your identity. For more information, see Authentication. Rutter uses the access_token query parameter to determine which Connection to fetch data for.

The response will be a Fetch All Orders response.

Congratulations, you successfully set up Rutter with your JavaScript app!


What’s Next