OAuth 1.0a for server-side web apps

Note

This content is provided as a reference for existing apps that implement OAuth 1.0a and OpenID 2.0. New or existing developers with no previous apps must implement OAuth 2.0 and OpenID Connect.

In order for your app to access your user’s QuickBooks company, they must authorize your app to access it. The QuickBooks Online API uses OAuth 1.0 to give apps access to data in a user’s QuickBooks company.

Once initiated, the app interacts with the Intuit OAuth service and your user to get authorization. This authorization persists via the Oauth access token you store on behalf of the customer—eliminating the need for this customer to re-authorize the connection on subsequent launches of your app. The OAuth access token represents the authorization for a unique combination of the user, company, and app. In other words, a valid OAuth access token means that user has successfully connected the app to their QuickBooks company.

Note

  • Only the Master Administrator or a Company Administrator can authorize access to a QuickBooks company.
  • Only one user at a time can be connected to a given company. Learn how an app connection can transfer to another user.

Overview

qbo/docs/develop/authentication-and-authorization/OAuth1Flow.png

Here’s what happens during the OAuth authorization workflow:

  1. An app requests a set of temporary token credentials, also known as a request token. These are not yet associated with any specific user’s QuickBooks.
  2. The app directs the user to an Intuit page, where the temporary token credentials are approved and linked to the user’s QuickBooks.
  3. The app exchanges the temporary token credentials for permanent token credentials, known as an access token. These credentials give the app access to the user’s company data via the QuickBooks Online API.

Implementing the OAuth authorization workflow

The OAuth flow must be executed once for every QuickBooks Online company to which a given App connects. At the end of this guide you will be able to connect your application to a QuickBooks Online company. For a detailed explanation of the OAuth 1.0a workflow please see the OAuth Community Site and the OAuth Core 1.0 Revision A.

Intuit OAuth Service endpoints

INTUIT OAUTH SERVICE ENDPOINT URL
Request token request https://oauth.intuit.com/oauth/v1/get_request_token
User authorization https://appcenter.intuit.com/Connect/Begin
Access token request https://oauth.intuit.com/oauth/v1/get_access_token

Prerequistes

  • Get Consumer Key and Consumer Secret Obtain OAuth 1.0 client keys from your app’s dashboard on developer.intuit.com. To locate the app’s dashboard, sign in to developer.intuit.com and click My Apps. Find and open the app you want. From here, click the Keys tab. There are two versions of this key:
  • Development keys—use only in the sandbox environment.
  • Production keys—use only in the production environment. Here is how to get your production keys.
  • Define your OAuth callback URL Your endpoint to process request token information and to get the access token. This URL is sent with the request token request.
  • Define the connect request URL This URL points to your request token endpoint and is defined with the grantUrl parameter in the setup() function. The flow is initiated:
  • From the QuickBooks app store: once your user clicks the Get App Now button on your app card.
  • From outside the QuickBooks App Store, when your user clicks the Connect to QuickBooks button that you place in one or more user-facing pages of your app.

1. Getting the OAuth request token

Implement your Request Token REST endpoint. The Request Token endpoint is the first of your endpoints that gets invoked during the OAuth 1.0a workflow. It is responsible for asking the Intuit OAuth API for a request token tuple—request token and request token secret, persisting said tuple on the appropriate company, and redirecting the user’s browser to Intuit’s Authorize URL.

To perform the steps in this section, you need the the following pieces of information:

  • Consumer Key and Consumer Secret—keys are private keys generated when you create an app. To find and copy these keys, sign in to developer.intuit.com and click My Apps. Find and open the app you want and click the Keys tab.
  • OAuth callback URL—your endpoint to process request token information and to get the access token.

Making the request

Initiate the OAuth 1.0a process by redirecting the user to Intuit’s OAuth 1.0 server. .:

1
GET https://oauth.intuit.com/oauth/v1/get_request_token

The set of query parameters supported by this endpoint include (all values are double URL encoded):

FIELD DESCRIPTION
oauth_callback The URL to which the Service Provider redirects the user back after user authorization is complete. It processes the request token request response and that sends the subsequent request for the access token.
oauth_consumer_key Identifies which app is making the request. Obtain this value from the Keys tab on the app profile via My Apps on the developer site. There are two versions of this key: - Development key—use only in the sandbox environment. - Production key—use only in the production environment.
oauth_nonce A unique token your app generates for each request.
oauth_signature A unique string your app generates for each request. Do not attempt to generate this value manually, but rather use one of several OAuth community resources as appropriate to your language.
oauth_signature_method The OAuth signature method used by QuickBooks Data Services is HMAC-SHA1.
oauth_timestamp This value is the number of seconds since the Unix epoch at the point the request is generated, and should be easily generated in most programming languages.
oauth_version The OAuth version and is always set to 1.0.

Here is an example of a complete request token request URL:

1
2
3
4
5
6
7
8
https://oauth.intuit.com/oauth/v1/get_request_token
oauth_callback=https%3A%2F%2Fwww.mydemoapp.com/oauth-redirect&
oauth_consumer_key=qyprdTyaQup3io7lQdovMUIQLkGZxD&
oauth_nonce=4139723014036997003&
oauth_signature=eqjbD6s%2FZiZy8FiNU9uoaspF6Q4%3D&
oauth_signature_method=HMAC-SHA1&
oauth_timestamp=1468266043&
oauth_version=1.0

Handling the response

The Intuit OAuth service verifies the signature and consumer key sent in the request. If successful, it returns a request token and request token secret to the oauth_callback parameter that you specified in the request. A successful response to the request contains the following fields:

FIELD DESCRIPTION
oauth_token_secret The request token secret. Use this in the subsequent request for the access token.
oauth_token The request token. Use this in the subsequent request for the access token.
oauth_callback_confirmed This is always set to true. Use it to confirm that the Intuit Oauth service received oauth_callback from the request.

All response fields are returned as query parameters, as shown below:

1
2
3
4
https://www.mydemoapp.com/oauth-redirect?
oauth_token_secret=JiWG7SoufVIOcmETlqrw9uqxzsIWMdSXhFpWlycy&
oauth_token=qyprde44rARayVC7bqrIUhyMAWqGDX1zoKTIONKQYWlK8Twb&
oauth_callback_confirmed=true

If your app has not been registered at developer.intuit.com, the following error is returned:

1
https://www.mydemoapp.com/oauth-redirect?oauth_problem=consumer_key_unknown

2. Obtaining user authorization

Making the request

In order for your app to be able to exchange the request token tuple for an access token tuple, your app must obtain approval from the user by directing the user to the Intuit Oauth service’s User Authorization URL with the request token returned in the response as oauth_token from step 1 above.

1
GET https://appcenter.intuit.com/Connect/Begin

The query parameter supported by this endpoint:

FIELD DESCRIPTION
oauth_token The request token returned in the response as oauth_token from step 1 above.

Here is an example of a complete request token request URL:

1
2
GET https://appcenter.intuit.com/Connect/Begin?
oauth_token=qyprdlZHFToZFJR6KDT0YSVAMZdEbOSZF6TQHhWjEENhAjXd

If the user is not already signed in, they are presented with Intuit’s single sign-on page:

qbo/docs/develop/authentication-and-authorization/SSOModal.png

Handling the response

The Intuit Oauth service verifies the user’s identity and asks for consent. After the user authenticates with the Intuit Oauth service and grants permission for your app to access their QuickBooks company, the Intuit Oauth service constructs an HTTP GET request URL, and redirects the user’s web browser to the oauth_callback URL you provide in the request token request from step 1 above. A successful response to the request contains the following fields:

FIELD DESCRIPTION
oauth_token The request token.
oauth_verifier The verification code.
realmID The company ID of the QuickBooks company that was just authorized.

All response fields are returned as query parameters, as shown below:

1
2
3
4
https://www.mydemoapp.com/oauth-redirect?
oauth_token=qyprde44rARayVC7bqrIUhyMAWqGDX1zoKTIONKQYWlK8Twb&
oauth_verifier=svmhhd&
realmID=sssfew12

Keep track of the realmID from each response and check it against previous responses. A duplicate realmID means that a user’s existing connection has transferred to another user. Make sure your app handles this situation as appropriate. For instance, you may want to make sure you save settings from the first user.

3. Getting the OAuth access token

Implement your Access Token Ready REST endpoint. The Access Token Ready endpoint is the second of your endpoints that gets invoked during the OAuth 1.0 workflow. It performs the following actions:

  • Asks the Intuit OAuth API for an access token tuple (access token and access token secret).
  • Persists said tuple on the appropriate company.
  • Redirects the user’s browser to a web page that reloads the parent page and closes the popup.

This flow begins when the user is redirected back to your oauth_callback URL, which was passed to the OAuth request token request endpoint.

Making the request

Your app’s access token request looks something like the following:

1
2
3
4
5
6
7
8
https://oauth.intuit.com/oauth/v1/get_access_token?
oauth_consumer_key=qyprdTyaQup3io7lQdovMUIQLkGZxD&
oauth_signature_method=HMAC-SHA1&
oauth_version=1.0&oauth_verifier=svmhhd&
oauth_token=qyprdlZHFToZFJR6KDT0YSVAMZdEbOSZF6TQHhWjEENhAjXd&
oauth_timestamp=1228169662&
oauth_nonce=8B9SpF&
oauth_signature=5f78507cf0acc38890cf5aa697210822e90c8b1c%261fa61b464613d0d32de80089fe099caf34c9dac5

The set of query parameters supported by this endpoint include:

FIELD DESCRIPTION
oauth_consumer_key Identifies which app is making the request. Obtain this value from the Keys tab on the app profile via My Apps on the developer site. There are two versions of this key: - Development key—use only in the sandbox environment. - Production key—use only in the production environment.
oauth_nonce A unique token your app generates for each request.
oauth_signature A unique string your app generates for each request. Do not attempt to generate this value manually, but rather use one of several OAuth community resources as appropriate to your language.
oauth_signature_method The OAuth signature method used by QuickBooks Data Services. This is always set to HMAC-SHA1.
oauth_timestamp This value is the number of seconds since the Unix epoch at the point the request is generated, and should be easily generated in most programming languages.
oauth_version The OAuth version and is always set to 1.0.
oauth_verifier The verifier returned in the response during step 2.
oauth_token The request token returned in the response during step 2.

Here is an example of a complete request token request URL:

1
2
3
4
5
6
7
8
9
https://oauth.intuit.com/oauth/v1/get_access_token?
oauth_consumer_key=qyprdTyaQup3io7lQdovMUIQLkGZxD&
oauth_nonce=8B9SpF&
oauth_signature=5f78507cf0acc38890cf5aa697210822e90c8b1c%261fa61b464613d0d32de80089fe099caf34c9dac5
oauth_signature_method=HMAC-SHA1&
oauth_timestamp=1228169662&
oauth_version=1.0&
oauth_verifier=svmhhd&
oauth_token=qyprdlZHFToZFJR6KDT0YSVAMZdEbOSZF6TQHhWjEENhAjXd&

Handling the response

The Intuit OAuth service verifies the signature and consumer key sent in the request. If successful, it returns the access token tuple to the oauth_callback parameter that you specified in the request. A successful response to the request contains the following fields:

FIELD DESCRIPTION
oauth_token_secret The access token secret.
oauth_token The access token.

All response fields are returned as query parameters, as shown below:

1
2
3
https://www.mydemoapp.com/oauth-redirect?
oauth_token_secret=<system generated access token secret>&
oauth_token=<system generated access token>

Token storage best practices

In persistent storage, save the OAuth oauth_token, oauth_token_secret, and realmId, associating them with the user who is currently authorizing access. Your app needs these values for subsequent requests to the QuickBooks Online API. Be sure to encrypt the access token and access token secret before saving them in persistent storage. Then, decrypt the access token and store it in volatile memory during contexts in which calls to API resources are made. Examples of these contexts include:

  • The life of a signed-in user session.
  • The life of a connection.

Be sure to implement an auto-renew strategy for the OAuth access token and the access token secret because they expire after 180 days. See Manage OAuth Access Tokens for details.

Add the Connect to QuickBooks button

To enable the user to initiate this OAuth authorization workflow from you app, provide the Connect to QuickBooks button on one or more pages of your app. Upon clicking this button, a popup window appears that begins the user authorization flow. During this flow, the user selects a company and then authorizes your app to access the data.

Implement your app’s disconnect endpoint

Your app’s disconnect endpoint is the target for the app’s Disconnect link where it appears in authorized app lists and is defined by the Disconnect URL field on the app’s settings page. When the Disconnect link is clicked, the QuickBooks app store invalidates the app token thereby effecting the disconnect and redirects to this endpoint. This page serves to inform your users that their QuickBooks Online connection has been terminated and provides reconnect instructions. Tasks this page must handle:

  • Intuit single sign-on apps
    • As appropriate, cleanup any internal tables that keep track of of your app’s connections and user settings so they have up-to-date connection information.
    • Map authenticated user information returned from OpenID services to the existing account, and provide the Connect to QuickBooks button.
  • Non-single sign-on apps
    • Provide a static page confirming the disconnect and information on where to go to reconnect.

Testing your OAuth implementation

In the sequence below, you sign in as a customer would and start the OAuth workflow by clicking the Connect to QuickBooks button. You may test this flow with either the development or production instance of your app.

  1. Go to the landing page of your app and verify that your app displays the Connect to QuickBooks button:
qbo/docs/develop/authentication-and-authorization/C2QB_white_btn_lg_default.png
  1. Click Connect to QuickBooks.
  2. In the Intuit sign-in window, enter the user ID and password.
  3. Verify that the company selector window (realm picker) pops open and shows the user’s QuickBooks companies. If the user has only one company, this dialog is not shown. Select a company.
qbo/docs/develop/authentication-and-authorization/OAuthPattyAlmost.png
  1. Verify that the authorization window appears:
qbo/docs/develop/authentication-and-authorization/OauthPattyAuthorize.png
  1. Click Authorize and verify that control returns to your app.

Go to the other pages of your app that display the Connect to QuickBooks button and repeat the testing sequence.

Transferring an app connection

When a connection is transferred

  • The current admin user is disconnected and current OAuth access token and access token secret are revoked.
  • The new admin user is connected and a new OAuth access token and access token secret are generated.

Only one admin user at a time can be connected to a given QuickBooks company. A second admin user attempting to connect, presented with the dialog below, must take action for the connection to transfer to them.

qbo/docs/develop/authentication-and-authorization/ReactiveDisconnect.jpg

This dialog informs the second user that only one user at a time can be connected to the QuickBooks company and provides a warning that the current user’s app tokens are lost if the second user connects. Additionally, if the second user chooses to connect anyway, an email is sent to the first user informing him that his connection was disconnected.

Managing OAuth access tokens

Your Oauth access token should not expire. If a user disconnects, or if token does expire, your application needs to handle the OAuth token renewal use case.

OAuth token life, renewal, and expiration

Oauth Access tokens expire 180 days from the date they were created. Oauth token Reconnect API can be called between 151 days and 179 days (after 5 months and before expiry).

  • Requesting a token to be renewed before 151 days results in this error Token Refresh Window Out of Bounds.
  • Requesting a token to be renewed after 179 days results in this error OAuth Token Rejected.
  • For information on the specific error codes and messages returned, see Reconnect API.

OAuth access token renewal strategy

To prevent your user from needing to sign-on to reauthorize access to your app every six months, follow these guidelines:

  1. Initiate the OAuth workflow to generate the initial access token for the user.
  2. Store the access token creation date within your app.
  3. Call the Reconnect API between 151 days and 179 days of that creation date to renew the Oauth access token.
  4. Repeat steps 2 and 3 after getting new token.

References

Sample OAuth implementations

Click the links below for sample implementations.

OAuth Community Resources

To implement the OAuth routines in your app, Intuit recommends using a standard library, such as:

For more information about OAuth, see the OAuth Community Site and the OAuth Core 1.0 Revision A. In OAuth terminology, your app is the consumer and Intuit is the service provider.