Integrating Freshbooks API into an Expo App

expo freshbooks oauth react native software

So recently, I've been working on an Internal BiteSite staff application. Besides being useful to our team, it is also a testing ground for us to up our mobile development game.

One of the things we do at BiteSite is track our billable time using Freshbooks and to keep ourselves on track, we have weekly targets that we like to hit. It's not a strict thing - but a good way for us to gauge how we're doing.

With that, I wanted to create a feature in the app where we could easily see how close to our target we are. To achieve this, I had to integrate into the Freshbooks API. Although each piece wasn't too hard - there were a LOT of steps to take care of to make this work.

This article will outline all the steps I took to achieve this. This implementation is for an Expo App using Expo's AppAuth - but I'm sure this can easily be adapted for a bare React Native app using the regular React Native AppAuth.

Alright here we go.

TL;DR

If you just want to see the code, hit up the Gist here.

Before we begin

Before we begin, I want to mention that we will be using a library called expo-app-auth. Expo AppAuth is based on the React Native AppAuth library which itself is based on AppAuth libraries for iOS and Android. In this article, when we talk about AppAuth, we're talking about the Expo version - but a lot I'm sure applies to all of these libraries.

Pre-coding setup

So before you start coding your integration, you need to actually create a Freshbooks app. You can find the full instructions here, but basically, you login to your Freshbooks account and hit up the developer page. Once there you just create an app.

At that point, you should have Client ID and a Client Secret.

Before we move on, you should add one more thing. Click on 'Edit Application', and add a redirect URI. I used the value 'exp://127.0.0.1:19000/--/auth/redirect'. The URL will have to be a Deep Link (which you can generate using Linking.makeUrl.

Update: So to get the redirect URI to work with standalone apps, you have to do a little bit of manual URI generation. As of the writing of this article, Linking.markUrl will produce a triple slash URI. For example, if you set your scheme in your app.json to bitesite, and you call Linking.markUrl('/auth/redirect'), you'll end up with bitesite:///auth/redirect. So while the above exp:// URI will work when using the Expo Go app, it won't work when you deploy to a standalone app. So you'd think that all you have to do is add the bitesite:/// triple slash URL to the Freshbooks App. Unfortunately, Freshbooks doesn't consider this a valid URL at this point. As such, you'll have to manually code in the redirect URI to be only double-slash and then add bitesite://auth/redirect to the Freshbooks App. See the code below to see how I do it using app.json.

Ok, so your setup is complete - you'll have a Client ID, a Client Secret, and a Redirect URI.

Where to store your Client ID and Client Secret?

This is probably the most annoying part of this article if you're looking to implement something quick. Unfortunately doing something quick will ultimately be insecure.

Alright, so one of the issues with coding Expo apps is your effectively coding a Javascript bundle that can easily be exposed. As such, the authors of AppAuth recommend that you do NOT hard code your Client ID and Client secret into your Javascript. Sure you can test it out this way, but you shouldn't be storing in the code.

As such, we opted to store this in our own Rails app in the Database.

The Expo app that we're coding in this article will talk to 2 servers:

  1. The BiteSite web app
  2. Freshbooks

If you're cooding this for yourself, you will have to find your own way to store the Client ID and Secret (or at minimum the secret) somehwere that's not your code.

Our BiteSite web app's API only allows authorized users to then fetch the Client ID and Client Secret.

Building the Freshbooks API Client Object

When I started working on this, I really wanted to have a Javscript object that handled the complexity of authenticating against the Freshbooks API and making all the calls. When it comes down to it, this object can really be boiled down to a few basic functions

  • Authenticate the user against Freshbooks and store the resulting OAuth Token
  • Check if the user has an OAuth Token
  • Refresh the OAuth Token if necessary
  • Make Freshbooks API Calls using the OAuth Token

So let's create a basic object and add all the imports we'll need:

/* freshbooks_api_client.js */
import axios from 'axios';
import Constants from 'expo-constants';
import * as AppAuth from 'expo-app-auth';
import * as Linking from 'expo-linking';
import * as SecureStore from 'expo-secure-store';
import moment from 'moment';
import apiClient from './api_client';
import appSettings from '../../app.json';

const FRESHBOOKS_AUTH_KEY = 'freshbooks_auth';

const freshbooks_api_client = {
  /* We'll build our code here */
};

export default freshbooks_api_client;

Let's look at each of these in detail.

Log the user in to Freshbooks

So the very first step is we need to get the user to sign in. So to do this, we're going to use the expo-app-auth library which you can see is imported as AppAuth above.

Now, since a LOT of the code to get a new token and to refresh a token is very similar, I created an internal function. For lack of a better name, I called it internalAuthorize.

/* freshbooks_api_clients.js */
...

const FRESHBOOKS_AUTH_KEY = 'freshbooks_auth';

function internalAuthorize(refreshToken) {

  const internalAuthorizePromise = new Promise((resolve, reject) => {
    let authState;

    apiClient.get('/settings')
      .then(({ data: settings }) => {

        let freshbooksApiClientId;
        let freshbooksApiClientSecret;

        settings.forEach((setting) => {
          if(setting.name === 'freshbooks_api_client_id') {
            freshbooksApiClientId = setting.value;
          }

          if(setting.name === 'freshbooks_api_client_secret') {
            freshbooksApiClientSecret = setting.value;
          }
        });

        let redirectUri = Linking.makeUrl('/auth/redirect');

        if(Constants.appOwnership === 'standalone') {
          redirectUri = `${appSettings.expo.scheme}://auth/redirect`;
        }

        const config = {
          serviceConfiguration: {
            authorizationEndpoint: `https://auth.freshbooks.com/service/auth/oauth/authorize?response_type=code`,
            tokenEndpoint: 'https://api.freshbooks.com/auth/oauth/token'
          },
          redirectUrl: redirectUri,
          clientId: freshbooksApiClientId,
          clientSecret: freshbooksApiClientSecret,
          scopes: [],
        };

        if(refreshToken) {
          console.log("Attempt to refresh token...");
          return AppAuth.refreshAsync(config, refreshToken);
        } else {
          return AppAuth.authAsync(config);
        }
      })
      .then((returnedAuthState) => {
        authState = returnedAuthState;
        return SecureStore.setItemAsync(FRESHBOOKS_AUTH_KEY, JSON.stringify(authState));
      })
      .then(() => {
        resolve(authState);
      })
      .catch(() => {
        SecureStore.deleteItemAsync(FRESHBOOKS_AUTH_KEY).then(() => {
          resolve();
        });
      });
  });

  return internalAuthorizePromise;

}

const freshbooks_api_client = {
  ...
};

export default freshbooks_api_client;

This function returns a promise that basically resolves with an authState object if the authorization is successful and with nothing (undefined) if it's not successful.

The first 10 lines or so are just a get request to get the Client ID and Client Secret that is stored on the BiteSite app. apiClient is an axios api client for the BiteSite web app. So this is where your code will differ.

Once you have the Client ID and Client Secret though, you should be good to go.

Because Freshbooks doesn't use standard OAuth Provider data, we have to custom configure the AppAuth.authorize request. This is one of the keys that's hard to find in other places. Take note of the URL, the Client ID, the Client Secret, and the Redirect URI. Again the Redirect URI might not ultimately matter. Particularly the URL - do NOT use the Authentication URL from Freshbooks. AppAuth automatically constructs a URL using the values you pass into the config object so follow the code closely above.

With this configuration, you'll properly hit the Freshbooks Authentication URL.

What's great, is everything that follows is handled by the AppAuth library. All you have to do is call AppAuth.authAsync(config) and AppAuth will properly bring up a Browser window for the user to login into Freshbooks. If the user successfully logs in, the call to AppAuth.authAsync(config) returns a promise that resolves with the authState object which contains all the token information you need to make Freshbooks calls.

So once we have that, we simply store in using SecureStore.setItem.

Now that the token is stored, we are ready to use it to make Freshbooks API calls.

Now this internal function is used both in authorization and refreshing tokens. I just control this with a true/false parameter. So if we want to authorize, we just call internalAuthorize() and if we want to refresh, we call internalAuthorize(true).

To expose the authorization piece to the public, I wrap this call in a function:

/* freshbooks_api_clients.js */
...

function internalAuthorize(refresh) {
  ...
}

const freshbooks_api_client = {
  authorize: function() {

    const authorizePromise = new Promise((resolve, reject) => {

      internalAuthorize().then((authState) => {
        if(authState) {        
          resolve(true);
        } else {
          resolve(false);
        }
      });

    });

    return authorizePromise;
  },
};

export default freshbooks_api_client;

And with that, if somebody wants to authorize, they can just do this:

/* AnotherFile.js */
import freshbooks_api_client from '../path/to/freshbooks_api_client';

freshbooks_api_client.authorize().then((authorized) => {
  if(authorized) {
    console.log("Authorization succeeded!")
  } else {
    console.log("Something went wrong.");
  }
});

Check user's authorization state

Ok now that we logged the user in, throughout the rest of the app, it would probably be nice to check whether or not the user is 'logged into Freshbooks'. Really what that is is just checking whether or not we have a stored token.

What you should know is that the authState that came back when we authenticated is not just a string. It actually contains a lot of information including the token itself, its expiry date, etc. That's why when we originally stored it, we converted it (serialized it) into a string using JSON.stringify:

  ...
  return SecureStore.setItemAsync(FRESHBOOKS_AUTH_KEY, JSON.stringify(authState));
  ...

So if we want to check the if the user is logged in, and use the accessToken, it might be nice to have a little function that extracts out the serialized object, and deserializes it back into an object. So to do that, I created another internal function:

/* freshbooks_api_client.js */
...
function internalAuthorize(refresh) {
  ...
}

function getFreshbooksAuth() {
  const getFreshbooksAuthPromise = new Promise((resolve, reject) => {
    SecureStore.getItemAsync(FRESHBOOKS_AUTH_KEY)
    .then((data) => {
      if(data) {
        const freshbooksAuthObject = JSON.parse(data);
        resolve(freshbooksAuthObject);
      } else {
        reject('Could not find freshbooks auth object');
      }
    })
    .catch((error) => {
      reject(error);
    })
  });

  return getFreshbooksAuthPromise;
};

const freshbooks_api_client = {
  ...
};

export default freshbooks_api_client;

This internal function getFreshbooksAuth simply goes into our SecureStore, grabs the value, parses it into a Javascript object and returns a promise that resolves with the object.

The object that is resolved is basically the original authState object we got when we authenticated against Freshbooks.

Now we just need to this to the outside world. If the token exists, we're considered authorized.

/* freshbooks_api_client */
...
const freshbooks_api_client = {
  ...
  checkAuthorization: function() {
    const checkAuthorizationPromise = new Promise((resolve) => {
      getFreshbooksAuth()
      .then((freshbooksAuthObject) => {
        console.log("Freshbooks token active.");
        resolve(true);
      })
      .catch((error) => {
        resolve(false);
      });
    });

    return checkAuthorizationPromise;
  }
}

Refresh the token

Now that we have a way to check if we're authorized, we should be clear to make any API calls. Not exactly. Above, when I said "If the token exists, we're considered authorized" - that wasn't entirely true.

The think about OAuth tokens is that the expire - and actually - they expire pretty quickly. In some cases within 24 hours. Luckily, it's pretty easy to refresh the token.

So we need to modify our checkAuthorization slightly if we have a stored token but it's expired, we just need to refresh it.

/* freshbooks_api_client */
...
const freshbooks_api_client = {
  ...
  checkAuthorization: function() {
    const checkAuthorizationPromise = new Promise((resolve) => {
      getFreshbooksAuth()
      .then((freshbooksAuthObject) => {

        if(moment().isAfter(freshbooksAuthObject.accessTokenExpirationDate)) {

          internalAuthorize(freshbooksAuthObject.refreshToken).then((authState) => {
            if(authState) {
              console.log("Freshbooks Token refreshed.");
              resolve(true);
            } else {
              console.log("No Freshbooks Token found.");
              resolve(false);
            }
          });

        } else {
          console.log("Freshbooks token active.");
          resolve(true);
        }
      })
      .catch((error) => {
        resolve(false);
      });
    });

    return checkAuthorizationPromise;
  }
}

Notice that we're using our internalAuthorize that we coded before. Again - logging in and refreshing the token uses very similar code. Once the authState comes back from the refresh, we just store it the exact same way we stored the original authState.

So now, when we call checkAuthorization, if we're not logged in, we get a 'false' response, if we're logged in, we get a 'true' response, and if we need a refresh, the refresh happens and we get a 'true' response.

With this in place, any file can now easily check authorization status:

/* AnotherFile.js */
import freshbooks_api_client from '../path/to/freshbooks_api_client';

freshbooks_api_client.checkAuthorization().then((authorized) => {
  if(authorized) {
    console.log("Authorized!")
  } else {
    console.log("Something went wrong.");
  }
});

Make Freshbooks API Calls

Alright, now we're finally ready to make calls to the Freshbooks API. Making calls to the Freshbooks API is actually pretty simple - you just have to pass in a special string as the authorization header for your request.

The string looks like this:

"Bearer YOUR_OAUTH_API_TOKEN"

Since we have the API Token, this is actually pretty simple. Remember that we already have the internal getFreshbooksAuth function to grab the authState object. This object has a property called accessToken that we can use.

So we just set up an Axios instance with the proper header to make the API call. For those that are not familiar with Axios and use things like jQuery, think of Axios as another way to execute something like $.ajax.

So to put this together, I created a get function on our exported object:

/* freshbooks_api_client.js */
...

const freshbooks_api_client = {
  ...
  get: function(url) {

    const getPromise = new Promise((resolve, reject) => {
      getFreshbooksAuth()
      .then((freshbooksAuthObject) => {
        const internalFreshbooksApiClient = axios.create({
          baseURL: `https://api.freshbooks.com/`,
          headers: {
            'Accept': 'application/json',
            'Api-version': 'alpha',
            'Authorization': `Bearer ${freshbooksAuthObject.accessToken}`
          },
        });

        internalFreshbooksApiClient.get(url).then((response) => {
          resolve(response);
        })
        .catch(() => {
          reject();
        });
      });
    });

    return getPromise;


  }

With that final piece, we can now make calls from other files easily:

import freshbooks_api_client from '../path/to/freshbooks_api_client';

freshbooks_api_client.checkAuthorization().then((authorized) => {
  if(authorized) {

    freshbooks_api_client.get('/auth/api/v1/users/me').then((response) => {
      console.log(response.data.response);
    }
  } else {
    console.log("Something went wrong.");
  }
});

Conclusion

So with that, we now have a nicely encapsulated library with a pretty simple API:

freshbooks_api_client.checkAuthorization();
freshbooks_api_client.authorize();
freshbooks_api_client.get('/freshbooks/api/end_point');

I'm sure there is a lot of cleanup that can be done, but for now this is working and I'm pretty happy with it. Hope this helps others as well!

If you want to see the source code for our Mobile App, check it out here.

And as that will always be evolving, you can check out the Gist here.

Casey Li
CEO & Founder, BiteSite