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.
Here are the main steps
- Setup Rutter Link in your frontend
- Exchange a public_token for an access_token from Rutter in your backend
- 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:
1<script src="https://cdn.jsdelivr.net/npm/@rutter/rutter-link@latest" 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.
1<!DOCTYPE html>
2<html>
3 <head>
4 <script src="https://cdn.jsdelivr.net/npm/@rutter/rutter-link@latest" type="text/javascript"></script>
5 <script>
6 function loadRutter() {
7 var rutterInstance = Rutter.create({
8 publicKey: "YOUR_RUTTER_PUBLIC_KEY",
9 onSuccess: function (publicToken) {
10 // Send publicToken to your backend and exchange
11 // https://docs.rutter.com/rest/2024-08-31/tokens
12 console.log("public token: " + publicToken)
13 }
14 })
15 rutterInstance.open();
16 }
17 </script>
18 </head>
19 <body>
20 <p><button onclick="loadRutter()">Load Rutter!</button></p>
21 </body>
22</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.
Direct Authentication
You can also pre-supply a commerce platform enum or accounting platform enum in Rutter Link to direct the merchant through a specific platform authentication.
1<!DOCTYPE html>
2<html>
3 <head>
4 <script src="https://cdn.jsdelivr.net/npm/@rutter/rutter-link@latest" type="text/javascript"></script>
5 <script>
6 function loadRutter() {
7 var rutterInstance = Rutter.create({
8 publicKey: "YOUR_RUTTER_PUBLIC_KEY",
9 onSuccess: function (publicToken) {
10 // Send publicToken to your backend and exchange
11 // https://docs.rutter.com/rest/2024-08-31/tokens
12 console.log("public token: " + publicToken)
13 }
14 })
15 rutterInstance.open({ platform: "SHOPIFY" });
16 }
17 </script>
18 </head>
19 <body>
20 <p><button onclick="loadRutter()">Load Rutter!</button></p>
21 </body>
22</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:
1<!DOCTYPE html>
2<html>
3 <head>
4 <script src="https://cdn.jsdelivr.net/npm/@rutter/rutter-link@latest" type="text/javascript"></script>
5 <script>
6 function loadRutter() {
7 var rutterInstance = Rutter.create({
8 publicKey: "YOUR_RUTTER_PUBLIC_KEY",
9 onSuccess: function (publicToken) {
10 // Send publicToken to your backend and exchange
11 // https://docs.rutter.com/rest/2024-08-31/tokens
12 callBackendAPI(publicToken)
13 }
14 })
15 rutterInstance.open();
16 }
17 </script>
18 </head>
19 <body>
20 <p><button onclick="loadRutter()">Load Rutter!</button></p>
21 </body>
22</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.
1const axios = require('axios');
2
3async function backendHandler(publicToken, userId) {
4 const res = await axios.post("https://sandbox.rutterapi.com/versioned/item/public_token/exchange",
5 {
6 client_id: "YOUR_RUTTER_CLIENT_ID",
7 secret: "YOUR_RUTTER_SECRET",
8 public_token: publicToken
9 },
10 {
11 headers: {
12 "X-Rutter-Version": "2024-08-31"
13 }
14 })
15 const access_token = res.data.access_token;
16 // Save the access_token and associated userId in your DB
17 saveAccessTokenForUser(access_token, userId);
18}
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:
1axios.get("https://sandbox.rutterapi.com/versioned/orders", {
2 params: {
3 access_token: "RUTTER_ACCESS_TOKEN",
4 limit: 1
5 },
6 auth: {
7 username: "RUTTER_CLIENT_ID",
8 password: "RUTTER_SECRET"
9 },
10 headers: {
11 "X-Rutter-Version": "2024-08-31"
12 }
13})
Rutter uses HTTP Basic Authentication to verify your identity. For more information, see Authorization. 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!