OAuth Management API

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.

The information on this page is for OAuth 1.0a implementations. This section provides a reference to OAuth management APIs:

  • Intuit OAuth Service URLs—Intuit OAuth Services endpoints.
  • setup()—JavaScript used to specify the URL needed by the Connect to QuickBooks button.
  • Disconnect—Endpoint used to disconnect the user from QuickBooks for this app.
  • Reconnect—Endpoint used to invalidate the the current OAuth access token and to generate a new one.

​For complete details about implementing OAuth in your app, click here.

Intuit OAuth Service URLs

  • Request token URL is:  https://oauth.intuit.com/oauth/v1/get_request_token
  • User authorization URL is: https://appcenter.intuit.com/Connect/Begin
  • Access Token Request URL is: https://oauth.intuit.com/oauth/v1/get_access_token

setup()

Function

intuit.ipp.anywhere.setup(​)

Parameters
  • grantUrl—The URL of the code on your site that begins the user authorization flow by getting an OAuth request token.  The flow is initiated when the user clicks the Connect to QuickBooks button.  This URL points to the Request Token Code.  Make sure this matches the value of the Host Name Domain field in your app's setting page on its Development tab.  To see the app's settings, select the app from My Apps  
  • datasources—The datasources you are accessing from your app.
    • quickbooks—Enable access to QuickBooks company. If not specified, default is true.
    • payments—​Enable access to QuickBooks payment data. If not specified, default is false
  • ​paymentOptions—Payment options if datasources.payments is set to true.
    • intuitReferred—Indicates whether merchant being sent through the connect to QuickBooks flow is referred by Intuit or not. If not specified, default is true: referred by Intuit.
DescriptionThe intuit.ipp.anywhere.setup() function specifies the URL needed by the Connect to QuickBooks button.
<script src="https://js.appcenter.intuit.com/Content/IA/intuit.ipp.anywhere-1.3.3.js" type="text/javascript"></script>
<script type="text/javascript">
    intuit.ipp.anywhere.setup({
            grantUrl: 'http://www.mycompany.com/HelloWorld/RequestTokenServlet',
            datasources: {
                 quickbooks : true,
                 payments : true
           },
            paymentOptions:{
                  intuitReferred : true
           }
    });
</script>

Disconnect

 
URIhttps://appcenter.intuit.com/api/v1/connection/disconnect
HTTP MethodGET
DescriptionInvalidates the OAuth access token in the request, thereby disconnecting the user from QuickBooks for this app. Because accessing QuickBooks data requires a valid access token, when the user is disconnected, your app cannot access the user's QuickBooks company data. After disconnecting the user, your app should display the Connect to QuickBooks button.
AuthorizationThe request header must include the OAuth parameters defined by OAuth Core 1.0 Revision A.
Success Return CodeIf the request is successful, the value of <ErrorCode> is 0 and HTTP status code is 200.
Errors
  • If an HTTP error is detected, then the HTTP status code is not 200. 
  • If an HTTP error is not detected but the disconnect is unsuccessful, then the HTTP status code is 200 and the response XML includes the <ErrorCode> element with a non-zero value.   For example,  if the OAuth access token expires or is invalid for some other reason, then the value of <ErrorCode> is 270.

Example XML Responses

If the request is successful, the value of <ErrorCode> is 0, for example:

<PlatformResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://platform.intuit.com/api/v1">
    <ErrorCode>0</ErrorCode>
    <ServerTime>2011-11-23T17:15:27.21097Z</ServerTime>
</PlatformResponse>

The following response indicates that the OAuth token in the request is invalid:

<PlatformResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://platform.intuit.com/api/v1">
    <ErrorMessage>OAuth Token rejected</ErrorMessage>
    <ErrorCode>270</ErrorCode>
    <ServerTime>2011-11-24T17:45:27.11097Z</ServerTime>
</PlatformResponse>

Reconnect

 
URIhttps://appcenter.intuit.com/api/v1/connection/reconnect
HTTP MethodGET
DescriptionInvalidates the OAuth access token used in the request and generates a new one, thereby extending the life span by 180 days. Because accessing QuickBooks data requires a valid access token, when the OAuth access token is renewed, your app can continue to access the user's QuickBooks company data. 
AuthorizationThe request header must include the OAuth parameters defined by OAuth Core 1.0 Revision A.
Success Return CodeIf the reconnect is successful, the XML response includes the <ErrorCode> element with a 0 value, a new OAuthToken, and new OAuthTokenSecret.
Errors

For cases where the token renewal fails, the response includes one of three error codes and the corresponding error message.

  • Error code 270—The OAuth access token has expired.
  • Error code 212—The request is made outside the 30-day window bounds.
  • Error code 22—The API requires authorization. 
  • Error code 24—The app is not approved for the API.

Example XML Responses

If the request is successful, the value of <ErrorCode> is 0, for example:

<ReconnectResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://platform.intuit.com/api/v1">
    <ErrorMessage/>
    <ErrorCode>0</ErrorCode>
    <ServerTime>2012-01-04T19:21:21.0782072Z</ServerTime>
    <OAuthToken>qye2eIdQ5H5yMyrlJflUWh712xfFXjyNnW1MfbC0rz04TfCP</OAuthToken>
    <OAuthTokenSecret>cyDeUNQTkFzoR0KkDn7viN6uLQxWTobeEUKW7I79</OAuthTokenSecret>
</ReconnectResponse>

 

ErrorCode 270—The OAuth access token has expired:

<ReconnectResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://platform.intuit.com/api/v1">
    <ErrorMessage>OAuth Token Rejected</ErrorMessage>
    <ErrorCode>270</ErrorCode>
    <ServerTime>2012-01-04T19:21:21.0782072Z</ServerTime>
</ReconnectResponse>
 

ErrorCode 212—The request is made outside 30-day window bounds:

<ReconnectResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://platform.intuit.com/api/v1">
    <ErrorMessage>Token Refresh Window Out of Bounds</ErrorMessage>
    <ErrorCode>212</ErrorCode>
    <ServerTime>2012-01-04T19:21:21.0782072Z</ServerTime>
</ReconnectResponse>

 

ErrorCode 24—The app is not approved for the API: 

<ReconnectResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://platform.intuit.com/api/v1">
    <ErrorMessage>Invalid App Token</ErrorMessage>
    <ErrorCode>24</ErrorCode>
    <ServerTime>2012-01-04T19:21:21.0782072Z</ServerTime>
</ReconnectResponse>

Did you find this page helpful?
Your feedback helps us make our docs better. Please let us know if this page helped you, or if it needs improvement.

 Got Questions? Get Answers in our developer forums.