How To Find The Right Scopes For Your App

If you created your FreshBooks OAuth app before October 2021, then you’ll need to make sure to modify and add scopes to it. If you’re wondering what scopes is, check out our documentation that has everything you need to know here.

There are two ways to find the scopes required for your application:

Reading the Documentation

Start with reading the dedicated scopes page or the individual API page for the APIs that are in use by your application. The main scopes page gives you a summary of the scopes available for the FreshBooks APIs, while on the individual API pages, we have specified the access requirements for that API call.

For example, you can see the access requirement for the Clients API on the Client API docs page.

The API Error Response

As of October 2021, we now report on missing scopes in API calls. When you make an API call with insufficient scopes, you will receive an HTTP error with status code 403, which will include a message containing two things:

1. The scopes you provided
2. The scopes needed for the API call 

To best prepare your app, we suggest creating a duplicate app from the developer portal and making API calls that your production app requires. Make a note of all the scopes you require to run your application. Once you have identified the scopes you require, go ahead and edit your application to include the scopes and test it again. When you have verified that you are able to make all the API calls needed to run your app, you can then edit your production app to include the necessary scopes. Keep in mind that you’ll need your app’s users to authorize your app once again.

Let’s look at an example of how to do this. As you see in the screenshot, we have an app named ‘Time Tracker – 24 Hour’ which has the ‘admin:all:legacy’ scope:

This app makes Get calls to the time entries, projects, clients, billable items, me endpoint. It also makes a Post call to the time entries endpoint. Let’s review what scopes this app will need to work smoothly.


To identify this, we have created a staging app named ‘Test- TT -24 hour’ with a single scope ‘user:profile:read’:

First, we’ll authorize the test app and generate a bearer token. Once we have the bearer token, we will make the API calls required by our app using postman. Below you’ll see an example where we made a time entries API call and got an error response with HTTP error code 403, which included a message naming the scope we are missing: ‘user:time_entries:read’.

After making all the API calls, we noted that the following scopes will be required by our app

user:time_entries:read
user:time_entries:write
user:projects:read
user:clients:read
user:billable_items:read

We’ll have to add these scopes to our staging app, re-authorize, and get a new bearer token. Using the new bearer token, make the API calls once again to ensure you did not miss any scopes.

Now that we’ve tested out our scopes, we’ll add this to our production app ‘Time Tracker – 24 Hour’. The next step will be to provide the new authorization link to our app users, so that they’re able to reauthorize the app.

Still have questions? Is something not working right? Don’t hesitate to reach out to us at api@freshbooks.com