OAuth Ruby Client

Here we will describe how to use the Intuit Ruby OAuth Client Library to generate access tokens for your QuickBooks Online company’s data. The Ruby OAuth Client Library provides a set of methods that make it easier to work with Intuit’s OAuth and OpenID protocol:

If you are not familiar with the Intuit OAuth protocol, please refer to Authentication and authorization page for general information on OAuth.

Note: The Ruby OAuth client requires Ruby version >= 1.9.0 and RubyGem version >= 1.3.5

The Ruby OAuth library uses gem for installation. To install the library, run:

1

gem install 'intuit-oauth'

You can also go to the Ruby OAuth Client Library to download the source code and run:

1

gem build intuit-oauth.gemspec

to build your own gem if you want to modify certain functions in the library.

In order to start using the library, the first step is to create a client object. Instantiate the IntuitOAuth object with your app’s client_id, client_secret, redirectUrl and environment. Valid values for the environment include sandbox and production. Be sure your to set your redirect_uri in your app settings under the corresponding environment.

1
2
3

require 'intuit-oauth'

client = IntuitOAuth::Client.new('client_id', 'client_secret', 'redirectUrl', 'environment')

After the client is created, use the client object to generate the authorization URL by specifying scopes. The following is an example:

1
2
3
4
5
6

scopes = [
    IntuitOAuth::Scopes::ACCOUNTING
]

authorizationCodeUrl = oauth_client.code.get_auth_uri(scopes)
# => https://appcenter.intuit.com/connect/oauth2?client_id=clientId&redirect_uri=redirectUrl&response_type=code&scope=com.intuit.quickbooks.accounting&state=rMwcoDITc2N6FJsUGGO9

Redirect your users to the authorizationCodeUrl and an authorization code will be sent to the redirectUrl defined. The authorization code will be exchanged for an OAuth 2.0 access token later.

Once the user has authorized your app, an authorization code will be sent to your RedirectURL defined in your client. Exchange the authorization code for an OAuth 2.0 token object.

1

result = oauth_client.token.get_bearer_token('The_authorization_code')

Your app must keep track of when a stored access token can be used and when the token must be refreshed. Use the refresh method to refresh the token when the token has expired. Always store the latest refresh token returned. Below is an example of how to use the refresh method to refresh a token:

1

newToken = oauth_client.token.refresh_tokens('Your_refresh_token')

If your app is disconnected by the user, you would need to revoke the token. Use revoke_tokens method to revoke the token:

1

trueOrFalse = oauth_client.token.revoke_tokens('the_token_you_want_to_revoke')

If OpenID scope is set when you generate the authorization URL, you can use get_user_info to get the user information:

1

result=oauth_client.openid.get_user_info('accessToken')

In case of HTTP Errors, the client raises OAuth2ClientException which has properties status_code, intuit_tid, timestamp, etc which can used for troubleshooting or while contacting Support.

Example exception:

1
2
3
4
5
6

IntuitOAuth::OAuth2ClientException: HTTP status 400, error message: {"error":"invalid_grant"}, intuit_tid: 779610af-1c14-adfd-9c04-f0fd1dedb303 on Mon, 03 Dec 2018 22:32:57 GMT
from /usr/local/lib/ruby/gems/2.4.0/gems/intuit-oauth-0.0.1/lib/intuit-oauth/utils.rb:67:in 'build_response_object'
from /usr/local/lib/ruby/gems/2.4.0/gems/intuit-oauth-0.0.1/lib/intuit-oauth/transport.rb:46:in 'request'
from /usr/local/lib/ruby/gems/2.4.0/gems/intuit-oauth-0.0.1/lib/intuit-oauth/flow/token.rb:66:in 'refresh_tokens'
from (irb):19
from /usr/local/bin/irb:11:in '<main>'

The below example shows how to construct the IntuitOAuth Client and use it to generate an OAuth 2.0 token.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

require 'intuit-oauth'

client = IntuitOAuth::Client.new('client_id', 'client_secret', 'redirectUrl', 'environment')
scopes = [
    IntuitOAuth::Scopes::ACCOUNTING
]

authorizationCodeUrl = oauth_client.code.get_auth_uri(scopes)
# => https://appcenter.intuit.com/connect/oauth2?client_id=clientId&redirect_uri=redirectUrl&response_type=code&scope=com.intuit.quickbooks.accounting&state=rMwcoDITc2N6FJsUGGO9

oauth2Token = oauth_client.token.get_bearer_token('the authorization code returned from authorizationCodeUrl')
# => #<IntuitOAuth::ClientResponse:0x00007f9152b5c418 @access_token="the access token", @expires_in=3600, @refresh_token="the refresh token", @x_refresh_token_expires_in=8726400>