FreshBooks, Ruby on Rails, and OAuth

In our experience working with OAuth, Ruby on Rails, and the Freshbooks API, we’ve found the documentation to be sadly lacking. In this post I’ll explain how we’ve managed to get these three to play nicely with each other. We’re running Ruby on Rails 3 with the ruby-freshbooks and oauth gems installed.

Getting Setup

1. We registered to be a FreshBooks OAuth application. It can take up to 5 days for them to approve your application, so you’ll want to do this step right away. To apply, login to FreshBooks, click on “My Account” then “FreshBooks API”. If you don’t already have a FreshBooks account, you’ll need to create one. Once registered, you will have the two key pieces of information needed to continue:
   • Consumer Key: Your FreshBooks system name (the portion of your account domain before freshbooks.com)
   • OAuth Secret: Found under “My Account” then “FreshBooks API”.
2. We added three fields to our users table in our database. You’ll need to be able to store each users FreshBooks URL, and if you don’t want them to have to log in to FreshBooks repeatedly, a place to store their access token and secret. (See the Token Expiry section in the Freshbooks OAuth Docs ).
3. We installed both gems (ruby-freshbooks 0.3.0 and oauth 0.3.6). UPDATE: We’ve found that different versions of these gems don’t work well with our code.
4. We installed our basic library code in the lib folder. We relied heavily here on the examples found in Paul Gallagher’s Twitter OAuth sample.

The Code

In a new Freshbooks controller we created three key actions:

Getting a Request Token
This action gets a request token from Freshbooks and stores it in the session for later. It then redirects the user to the FreshBooks authentication screen. They log in, and FreshBooks returns them (along with a verifier) to our callback method.

def request_token
  fb = FreshbooksOauth.new(current_user.fb_url)
  @request_token = fb.get_request_token(fb_callback_url)
  session[:fb_request_token] = @request_token.token 
  session[:fb_request_token_secret] = @request_token.secret
  redirect_to @request_token.authorize_url    
end

Callback
In the callback action, we get an access token and secret using the data we’ve gathered so far. We save those in the database so the user doesn’t have to repeatedly go through this process when they want to access Freshbooks data through our app. Then we redirect them to the show method where they can view the data.

def callback
  fb = FreshbooksOauth.new(current_user.fb_url)
  @access_token = fb.exchange_request_for_access_token(
          session[:fb_request_token], 
          session[:fb_request_token_secret], 
          params[:oauth_verifier])
  current_user.update_attributes(:fb_token=>@access_token.token.to_s, 
          :fb_secret=>@access_token.secret.to_s)
  redirect_to fb_show_path
end

Showing FreshBooks Data
The show action is what we send users to by default when they try to import FreshBooks data. If they have not been authenticated previously (i.e. we don’t have an access token or secret for them), or if there’s an authentication error we redirect them to the _request_token_ method to authenticate with FreshBooks. Otherwise we use the Ruby-FreshBooks gem to make a simple request to FreshBooks.

def show
  if((current_user.fb_token.blank? || current_user.fb_secret.blank?) 
      && session[:fb_error].blank?) 
    session[:fb_error] = true
    redirect_to fb_request_token_path 
    return
  end

  client = FreshBooks::Client.new(current_user.fb_url+'.freshbooks.com', 
          'YOUR FRESHBOOKS SUBDOMAIN HERE (i.e. clockwork)',
          'OAUTH SECRET HERE', 
          current_user.fb_token, 
          current_user.fb_secret)
  @invoices = client.invoice.list :status => 'unpaid'

  #If returns error
  if(@invoices['error'])
    #If first error, get new request token and try again
    if session[:fb_error].blank?
       session[:fb_error] = true
       redirect_to fb_request_token_path
    else
      session[:fb_error] = nil
      redirect_to freshbooks_path, 
              :notice => 'There was an authentication error'
    end
  end
end

We hope that this is helpful to you. Does the code work for you? Any suggestions for improvement? Let us know in the comments section below.

Downloads

FreshBooks Controller
FreshBooks OAuth Library

References

Ruby FreshBooks Gem
OAuth Gem
Rails Twitter OAuth Sample

Post a comment:

Name:
Email:
URL:

Click here to try another image.

Type the code shown: