Implement OAuth 1.0a

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

  • From the QuickBooks Online App Store, the OAuth workflow is initiated once your user clicks the Get App Now or Learn More buttons on your app card.
  • From outside the QuickBooks Online App Store, the workflow is initiated by clicking the Connect to QuickBooks button that you place in one or more user-facing pages of your app.

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, Company Administrator, or Accountant user can authorize access to a QuickBooks company. If an Accountant user is deleted from the company while they are connected to it, the QuickBooks API returns a 401 HTTP status code  and an authorization failure message with error code 120.
  • Only one user at a time can be connected to a given company. When a second user tries to connect, they receive the error:
                  The application has already been subscribed to by another user for this company.

This topic contains the following sections:​

Overview

Here's what happens during the OAuth authorization workflow:

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 company.
The app directs the user to an Intuit page, where the temporary token credentials are approved and linked to the user's QuickBooks company.
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 API.

    Implementing the OAuth authorization workflow

    The OAuth flow must be executed once for every QuickBooks Online company file 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 Intuit’s OAuth 1.0 flow please see the OAuth Community Site and the OAuth Core 1.0 Revision A.

    Intuit OAuth Service endpoints

    Intuit OAuth Service EndpointURL
    Request token requesthttps://oauth.intuit.com/oauth/v1/get_request_token
    User authorizationhttps://appcenter.intuit.com/Connect/Begin
    Access token requesthttps://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 on either the Development tab or the Production 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 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.

    One.pngGetting the OAuth request token

    Click to show details.

    Implement your Request Token REST endpoint.  The Request Token endpoint is the first of your endpoints that gets invoked during the OAuth 1.0 flow. 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 process by redirecting the user to Intuit's OAuth 1.0 server. .:

    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):

    FieldDescription
    oauth_callbackThe URL to whcih 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_keyIdentifies 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_nonceA unique token your app generates for each request.
    oauth_signatureA 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_methodThe OAuth signature method used by QuickBooks Data Services is HMAC-SHA1.
    oauth_timestampThis 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_versionThe OAuth version and is always set to 1.0.

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

    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:

    FieldDescription
    oauth_token_secretThe request token secret. Use this in the subsequent request for the access token.
    oauth_tokenThe request token. Use this in the subsequent request for the access token.
    oauth_callback_confirmedThis 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:

    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:

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

    two.pngObtaining user authorization

    Click to show details.

    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.

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

    The query parameter supported by this endpoint:

    FieldDescription
    oauth_tokenThe request token returned in the response as oauth_token from step 1 above.

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

    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:

    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:

    FieldDescription
    oauth_tokenThe request token.
    oauth_verifierThe verification code.
    realmIDThe company ID of the QuickBooks company that was just authorized.

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

    https://www.mydemoapp.com/oauth-redirect?
       oauth_token=qyprde44rARayVC7bqrIUhyMAWqGDX1zoKTIONKQYWlK8Twb&
       oauth_verifier=svmhhd 
    

    three.pngGetting the OAuth access token

    Click to show details.

    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:

    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:

    FieldDescription
    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_nonceA unique token your app generates for each request.
    oauth_signatureA 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_methodThe 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_versionThe OAuth version and is always set to 1.0.
    oauth_verifierThe verifier returned in the response during step 2.
    oauth_tokenThe request token returned in the response during step 2.

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

    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:

    FieldDescription
    oauth_token_secretThe access token secret.
    oauth_tokenThe access token.

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

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

    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 API. Be sure to encrypt the access token and access token secret before saving them in persistent storage. 

    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.

    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.

    Click here to see process.
    1. Go to the landing page of your app.
    2. Verify that your app displays the Connect to QuickBooks button:
      C2QBButton.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, for example:

    File:0050_QuickBooks_API/0020_Authentication_and_Authorization/Connect_from_within_your_app_(OAuth)/OAuthPattyAlmost.png

    1. Select a company and click Continue.
    2. Verify that the authorization window appears, for example:

    File:0050_QuickBooks_API/0020_Authentication_and_Authorization/Connect_from_within_your_app_(OAuth)/OauthPattyAuthorize.png

    1. Click Authorize.
    2. Verify that control returns to your app. 
    3. Go to the other pages of your app that display the Connect to QuickBooks button and repeat the testing sequence.

    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.

     Got Questions? Get Answers in our developer forums.