There are so many resources on the internet that explain how to properly do the dance. If you’ve ever tried to learn the newest viral TikTok dances or even the most basic line dance in your high school gym, you know quite well, they still take lots of practice.
I won’t try and reinvent the wheel, but what I will try to do is provide context on how to properly authenticate a FreshBooks user to your app. Who knows, maybe your new app will go viral (that sounds negative in this context…)
We’ll start off this tutorial with an expectation that you have a FreshBooks account (trial or paid), a basic understanding of what OAuth is and why you need to use it. To be explicit, we are going to be using the Authorization Code Grant flow of OAuth 2.0
I’m going to provide my snippets in Javascript (Express/Node) but the HTTP requests will be the same.
Getting Started:
From a human’s perspective, this is what’s going to happen. Someone on the internet (a user) wants to use the app you’ve created. In order to do so, they will need to provide your app with permission to make requests on its behalf and read and write information to your account.
To do so, you will give them an Authorization URL (that FreshBooks generates). This will link them to a custom Authorization page that FreshBooks hosts with the Client ID of your app associated with it. FreshBooks will ask the user to enter in their FreshBooks credentials in order to give you access to connect your app to their account.
Once the user logs in and clicks “Authorize Access”, the authorization server will redirect the user back to your page/app (using the Redirect URI you entered in the App creation) with the user’s code attached to it.
Since you own that site, you can query the request parameters, take the code of the user (which is always changing depending on the user), attach the Client ID and Client Secret of the app and redirect URI (all static and unchanging in your app) and exchange it for an Access Token and Refresh Token in FreshBooks.
Your app can now use the Access Token and Account ID to identify the user and prove you have been given permission make changes on the user’s behalf. Keep in mind that every 12 hours that Access Token expires, so you can use your Refresh Token (which never expires, but can only be used once) to get a new Access Token and keep going.
Once you get an Access Token and Refresh Token you should never technically need to reauthenticate the user and go through that entire flow again. (But naturally, there are a kabillion reasons why one might).
Now that we know the general overview, let’s get into the technical aspect of it. First, I’ll outline the steps and then we dive into each step after that
Step 1: Create An App on the FreshBooks Developer Portal Step 2: Dealing with the Authorization URL Step 3: User Approval and Redirect Step 4: Handling Redirects and Getting A Bearer/Access Token
Create An App on the FreshBooks Developer Portal First off you’ll need to create an app. You can do this by going to my.freshbooks.com/#/developer or you can login to your FreshBooks account.
Click on the Settings gear in the top left-hand corner
Choose the Developer Portal tab
Now click on Create an App in the top right-hand side of the screen.
You’ll also be required to select the Scopes required. You can read up on Scopes here
NOTE: It’s important you add full URLs, including the https:// prefix. It’s also important that if you are building a scalable app that you have a redirect_uri that you own because you want to be able to query the URL associated with that redirect.
Once this is created, you will be given an Authorization link in the App Management page.
Dealing withthe Authorization URL A user visits your Authorization link, which you supply on your website.
You can find this link on your App Management page. Feel free to add this link anywhere you like; we can also put it on our marketplace!
User Approval and Redirect Your Users are sent to an Authorization page we host. If the user is not logged in, they will be asked to and then sent to the below page. If the user is already logged in, they will go directly to this page.
Note: your app’s name, scope and info will show on this page.
The user logs in and clicks ‘Authorize’ to authorize your app.
They are redirected back to your website (redirect_url) with a code parameter in the URL.
Handling Redirects and Getting A Bearer/Access Token You consume that code appended to the redirect URL from step above, and send us a request from your server containing the same code, your client_id, client_secret, and the redirect_uri the user followed.
On line 17, I’m going to show you what that code looks like:
On line 18 we take that code and add it to our bearer function.
You can then make the the request for an access_token, you will also need to add client_id, client_secret and your redirect_uri (they must match).
NOTES:
It is only the code that is going to change on a user-by-user basis, everything else will remain static.
We only support authorization_code and refresh_token grant types
We return to you an access_token and refresh_token pair.NOTE: It’s important you encrypt these and store them safely in a database. There are plenty of libraries that can help you with this.
Your app can now make successful calls on that user’s behalf
Your access_token will expire every 12 hours, but your one time user refresh_token will never expire. You can use your old refresh_token to get a new access_token and a new refresh_token when your old access_token expires, but you need to change the code type from authorization_code to refresh_token as seen here. Be sure to record/store the new refresh_token it will be vital for when your access_token expires in 12 hours.
We use analytics cookies to ensure you get the best experience on our website. You can decline analytics cookies and navigate our website, however cookies must be consented to and enabled prior to using the FreshBooks platform. To learn about how we use your data, please Read our Privacy Policy. Necessary cookies will remain enabled to provide core functionality such as security, network management, and accessibility. You may disable these by changing your browser settings, but this may affect how the website functions.
To learn more about how we use your data, please read our Privacy Statement.
