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.
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.
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).
Before we will approve your Consumer registration, we need your company name. 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.
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.
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.
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.
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.
Because all requests must use SSL, only the PLAINTEXT signature method is supported.
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]'
Please note that the oauth_signature is produced from both the consumer signature and token secret. For more information on using the API, please see the FreshBooks API Documentation.
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.
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.
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.
By registering as an OAuth Consumer, you are agreeing to the following terms of service:
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).
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.