React Quickstart

Getting started with Rutter

In this guide, we'll go through the steps necessary to add Rutter to any React app. If you don't use React, see the JavaScript 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

Clone this NextJS sample repo for a working example.

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.

Bash

1npm install react-rutter-link
2# Or, using yarn
3yarn add react-rutter-link

Then, use our React Hook to trigger the authentication flow in your code. You will need to pass in your public_key as part of the Link configuration. You can find it in your Rutter Dashboard.

TypeScript

1import { useRutterLink } from 'react-rutter-link';
2
3function Component() {
4  
5 function onSuccess(publicToken) {
6   console.log(publicToken);
7 }
8
9 const rutterConfig = {
10   publicKey: "YOUR_RUTTER_PUBLIC_KEY",
11   onSuccess: onSuccess,
12   avoidCDN: false // optional, defaults to false. set to true to pull dependencies locally instead of from a CDN. 
13 }
14  
15 const { open } = useRutterLink(rutterConfig);
16  
17 return (
18    <div>
19    <Button onClick={() => open()}></Button> 
20  </div>
21 )
22}

Now, if you run the app and click the Button, the Rutter Link flow will appear. Once a merchant completes the flow, a publicToken, representing a successful authentication, will be passed to your onSuccess callback.

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.

TypeScript

1import { useRutterLink } from 'react-rutter-link';
2
3function Component() {
4  
5 function onSuccess(publicToken) {
6   console.log(publicToken);
7 }
8  
9 const rutterConfig = {
10   publicKey: "YOUR_RUTTER_PUBLIC_KEY",
11   onSuccess: onSuccess
12 }
13  
14 const { open } = useRutterLink(rutterConfig);
15  
16 return (
17    <div>
18    <Button onClick={() => open({ platform: "SHOPIFY" })}></Button> 
19  </div>
20 )
21}

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:

TypeScript

1import { useRutterLink } from 'react-rutter-link';
2
3function Component() {
4  
5 function onSuccess(publicToken) {
6   // Send publicToken to your backend, which will call the
7   // Rutter API to get an access_token
8   callBackendAPI(publicToken)
9 }
10  
11 const rutterConfig = {
12   publicKey: "YOUR_RUTTER_PUBLIC_KEY",
13   onSuccess: onSuccess
14 }
15  
16 const { open } = useRutterLink(rutterConfig);
17  
18 return (
19    <div>
20    <Button onClick={() => open()}></Button> 
21  </div>
22 )
23}

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.

TypeScript

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    client_id: "YOUR_RUTTER_CLIENT_ID",
6    secret: "YOUR_RUTTER_SECRET",
7    public_token: publicToken
8  },
9  {
10    headers: {
11      "X-Rutter-Version": "2023-03-14"
12    }
13  })
14  const access_token = res.data.access_token;
15  // Save the access_token and associated userId in your DB 
16  saveAccessTokenForUser(access_token, userId);
17}

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:

TypeScript

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": "2023-03-14"
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 List Orders response.

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