× FreshBooks App Logo
FreshBooks
Official App
Free - Google Play
Get it
You're currently on our US site. Select your regional site here:

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