Scopes

Scope is a mechanism in OAuth 2.0 that limits an application’s access to a user’s account. An application can request one or more scopes, this information is then presented to the user in the consent screen, and the access token issued to the application will be limited to the scopes granted.

At FreshBooks, we use scopes to ensure your application only has access to the resources allowed by a FreshBooks user.

For example, if you are a time-tracking app and you want to handle time entries for a user account, you would need to read the different businesses the identity has, read the projects to track time against, read the clients associated with the project, read the services for that business to track time against, and read or write time entries themselves. You would need the below scopes for such an application:

1. user:profile:read
2. user:projects:read
3. user:clients:read
4. user:billable_items:read
5. user:time_entries:read
6. user:time_entries:write

Please note that user:profile:read is added to all new apps by default as it’s needed for all basic calls to get started.

It’s not possible to remove scopes from an existing access token. The only way to reduce or add consented scopes is to revoke the token and start with the app authorization flow again. So make sure to test your application and confirm you request all the scopes that your application might require.

Types of Scopes

FreshBooks uses scopes that refer to the entity granting access (example: user), followed by the object they granted access to (example: user:clients), followed by the class of actions performed by that entity on the object (example: user:clients:read). 

The list of objects includes

1. bill_payments
2. bill_vendors
3. billable_items
4. bills
5. business
6. clients
7. credit_notes
8. estimates
9. expenses
10. invoices
11. journal_entries
12. notifications
13. online_payments
14. other_income
15. payments
16. profile
17. projects
18. reports
19. retainers
20. taxes
21. teams
22. time_entries

There are currently only two classes of action that can be performed on an object:

1. read: Reading the full information about a single resource.
2. write: Modifying the resource in any way (e.g. creating, editing, archiving, or deleting).

You can also access the complete list of all scopes and the corresponding endponts below