Authentication

There are two ways to authenticate when using the API – using a token-based method or OAuth. If you’re building an application for many other people to use (ie. iPhone App, Integration with Expensify), we recommend using OAuth, otherwise for things like recurring billing or invoicing integration into your organizations software, it’s easiest to use the token-based method.

• OAuth
• Token-Based Method

1) OAuth

The FreshBooks API now supports using OAuth to authorize applications that require access to users’ FreshBooks data. OAuth is an open protocol that allows secure API authorization without requiring the user to provide their user credentials to a third party. You can read more about OAuth here. FreshBooks conforms to the OAuth Core 1.0 Revision A specification.

Registering as a Consumer

To register as an OAuth consumer, sign up for a free FreshBooks account and enable OAuth by clicking on “My Account” and then “FreshBooks API”. Scroll down and you will see a checkbox labeled “Enable OAuth”. Selecting the checkbox will display a token to use as your OAuth Consumer Secret. Once OAuth has been enabled, FreshBooks will review your account and verify your request to be an OAuth Consumer. This process may take up to 5 business days. Once verified, your consumer key will be your FreshBooks system name (the portion of your account domain before freshbooks.com).

Two pieces of information are required before we will approve your Consumer registration:
1) Enter the name of your company or application as you would like it to appear to your users by going to “Settings” and entering a value in the “Company Name” field.

2) Upload an Invoice Logo by going to “Settings” and then “Colors & Logos”. Your company name and logo will be displayed to users when they are asked to authorize a request token from your application.

Request URLs

Because FreshBooks URLs change from account to account, the following URLs all use ‘sample.freshbooks.com’ as an example. You should substitute this with the appropriate URL for the user to whose data your application is requesting access.

Request Token URL

https://sample.freshbooks.com/oauth/oauth_request.php

You must use HTTP POST when requesting an unauthorized Request Token. Because FreshBooks uses 1.0 Revision A of the OAuth specification, the ‘oauth_callback’ parameter must be specified.

User Authorization URL

https://sample.freshbooks.com/oauth/oauth_authorize.php

HTTP GET should be used when sending a user to the User Authorization URL to authorize an OAuth Request Token. The user will then enter their FreshBooks account credentials using a secure form and the information will be sent to FreshBooks using HTTP POST. Upon verification of the user credentials, FreshBooks will redirect the user to the URL specified in the ‘oauth_callback’ parameter supplied when requesting an unauthorized Request Token.

Access Token URL

https://sample.freshbooks.com/oauth/oauth_access.php

You must use HTTP POST when exchanging an authorized Request Token for an Access Token. Once again, because FreshBooks uses 1.0 Revision A of the OAuth specification, the ‘oauth_verifier’ parameter must be specified.

Request Signing

Because all requests must use SSL, only the PLAINTEXT signature method is supported.

Accessing Protected Resources

Once you have obtained an OAuth Access Token, consumer applications can send OAuth Protocol Parameters in the HTTP Authorization header, as the HTTP POST request body or in the query string of the URL. For example, if your Access Token is ‘foo’, an example request using the curl command-line tool would look something like this:

curl -H 'Authorization: OAuth realm="",oauth_version="1.0",oauth_consumer_key="consumer",oauth_token="foo",oauth_timestamp="1251493984",oauth_nonce="GKork9OAIff",oauth_signature_method="PLAINTEXT",oauth_signature="36PEuJegNY47i5Qw645PjV7bQeVwG79879%26nDfi7Y2j7dA5aFR9SnecfxxmwQmysVHx"'' https://sample.freshbooks.com/api/2.1/xml-in -d '[xml body here]'

For more information on using the API, please see the FreshBooks API Documentation.

Token Expiry

Unauthorized Request Tokens are subject to expiry after one hour. If a Request Token is authorized within that time it will not be expired. At the moment we do not expire Access Tokens but may in the future give users the option of specifying a lifetime for their active Access Tokens.

Consumer Identity

In certain cases (i.e. desktop or mobile applications) a Consumer may need to send unsigned requests. If no Consumer secret is provided as part of the ‘oauth_signature’ parameter, the request will be accepted but the user will be presented with a warning when asked to authenticate the token originating from this Consumer.

Out of Band Configuration

If the Consumer specifies ‘oob’ as the ‘oauth_callback’ value, the user will be presented with the ‘oauth_verifier’ and ‘oauth_token’ response parameters instead of being redirected to the URL normally provided. These will have to be handled manually by the user.

OAuth Terms of Service

By registering as an OAuth Consumer, you are agreeing to the following terms of service:

1. Responsibility and Liability: FreshBooks is not responsible or liable for any direct or indirect consequences affiliated with using the FreshBooks API. Please be careful and use the FreshBooks API at your own risk.
2. Privacy: OAuth Consumers must protect the security and privacy of user information acquired through the FreshBooks API in accordance with the FreshBooks privacy policy.
3. Right to Modify: FreshBooks may update, modify or discontinue the FreshBooks API at any time with or without notice.
4. Suspension and Termination: FreshBooks reserves the right to suspend or terminate FreshBooks OAuth Consumers with or without reason and at any time.
5. Uptime: FreshBooks is not responsible for any downtime or slow down the API may experience.
6. Load: OAuth Consumers are responsible for not putting excessive load on the FreshBooks API.
7. Amendments: FreshBooks reserves the right to update these terms in the future with or without notice and at any time.

Other helpful resources

• OAuth Support for FreshBooks and the Gory Technical Details by Michael Mattax
• Freshbooks API using OAuth by Michael Helmick

2) Token-Based Authentication (Deprecated for add-ons)

For your account, you’ll be given a unique authentication token. For every API request you make, you’ll need to use HTTP basic authorization to present the unique authorization token assigned to you. The admin user, and each staff member, has an API token. The admin user’s authentication token can be found on the “FreshBooks API” page. The staff token can be found on each staff member’s Profile page, or on the Edit Staff page (for admin only). At this time, staff members have limited access to the API (see the individual method pages for details).

Please note your authentication token is based on your account password. If your password changes, so will your authentication token.

HTTP authentication traditionally takes a username/password pair, but since we’re dealing with a single token, you’ll only use the username field. If your HTTP library requires a password as well, just use an arbitrary string – like “X”.

Here’s an example authenticated request made with cURL:

curl -u insert_token_here:X https://sample.freshbooks.com/api/2.1/xml-in -d '[xml body here]'

Keep this token secret. It should be guarded just as you would your regular account password. If you feel your token has been compromised, you can reset it by clicking the “Reset” link on the “FreshBooks API” page.

Lastly, we also ask you use a unique User-Agent string to identify your application and/or organization.