How do I get started with my OAuth integration?
You need to create an app in order to have a container for the OAuth workflow. Only apps registered with the Intuit Developer portal can implement the OAuth workflow to access QuickBooks companies and the QuickBooks Online API. After registering your app, you receive a client ID and client secret:
one set for use with sandbox environments and one set for use with production QuickBooks companies. See Creating an app
for complete details.
What is a redirect URI and why is it required?
A redirect URI is the location in a third-party app where Intuit’s OAuth 2.0 service returns control at various junctures during the authorization process. Code at this location processes the initial authorization response, constructs the request for refresh and access tokens, and manages resulting
refresh and access tokens. A developer registers one set of redirect URIs for the development environment and one set for the production environment on the Keys tab of the app’s dashboard. The image below showcases the location of both sets of redirect URIs on the app’s Keys tab.
The Intuit OAuth 2.0 service redirects users to registered URIs, only, which helps prevent some attacks. Any HTTP redirect URIs must be protected with TLS security; as a result, the service will only redirect to URIs beginning with https. This prevents tokens from being intercepted during the
Within the development environment, an app registers a redirect URI for each 3rd party client wishing to gain access to the developer’s sandbox companies. Besides the app itself, such clients can include Postman, OAuth 2.0 playground, and so on.
What are refresh token and access token durations?
- Access tokens are valid for 3600 seconds (one hour), after which time you need to get a fresh one using the latest refresh_token returned to you from the previous request. If a request to the QuickBooks Online API returns the message, 401 unauthorized, the access_token has expired.
- The lifetime for the refresh_token returned with the initial access_token is set to 100 days.
- Always use the current refresh_token when requesting a new access_token. A new refresh_token is returned and the previous refresh_token is expired. This new refresh_token now has a lifetime of 100 days.
- If an access_token is not requested during the current refresh_token 100 day lifetime, the refresh_token expires and access to the QuickBooks company terminates.
- As long as it hasn’t expired, the refresh_token can be reset as often as needed from the time the original access_token was generated.
Click here for complete details on refreshing the access token.
Why does my refresh token expire after 24 hours?
Stale refresh tokens expire after 24 hours. Each time you refresh the access_token a new refresh_token is returned with a lifetime of 100 days. The previous refresh_token is now stale and expires after 24 hours. When refreshing the access_token, always use the latest refresh_token returned to you.
What is the purpose of scopes?
A scope corresponds to a level of access to Intuit user data or QuickBooks company data. The OAuth 2.0 authorization request includes the list of scopes you require. We recommend requesting scopes as needed. It is generally a best practice to request scopes incrementally, at the time access is
required, rather than up front. Each time you change the set of scopes you must initiate the authorization workflow again with the new list of scopes and you must get new access and refresh tokens. Current supported scopes include:
- com.intuit.QuickBooks.accounting—QuickBooks Online API
- com.intuit.QuickBooks.payment—QuickBooks Payments API
- openid—OpenID Connect processing
- profile—user’s given and family names
- email—user’s email address
- phone—user’s phone number
- address—user’s physical address
How to mitigate against cross-site request forgery (CSRF) in authentication requests?
You must protect the security of your users by preventing cross-site request forgery (CSRF) attacks. To mitigate against these attacks, include a unique session token in the authorization request, via the state query parameter, that holds
the state between your app and the user’s client. In turn, your app matches this unique session token with the one returned by the Intuit OAuth service in the authentication response to verify that the user, rather than a malicious attacker or bot, is making the request. These tokens are often
referred to as cross-site request forgery (CSRF) tokens.
One good choice for a unique session token is a string of 30 or so characters constructed using a high-quality random-number generator. Another is a hash generated by signing some of your session state variables with a key that is kept secret on your back-end. Click
here for more information.
When should I migrate from OAuth 1.0 to OAuth 2.0?
In July 2017, we announced that new apps would use OAuth 2.0 for authorization, and (optionally) OpenID Connect for single sign-on authentication.
We will disable OAuth 1.0 for existing apps as of December 17, 2019.
This means that all apps that still use OAuth 1.0 will need to migrate to OAuth 2.0 before December 17, 2019.
What will happen when QuickBooks disables OAuth 1.0?
Starting December 17, 2019:
- Intuit will revoke all existing OAuth 1.0 tokens.
- API calls that still pass OAuth 1.0 tokens in the Authorization header will fail.
- If an app sends users to the OAuth 1.0 consent flow to get a new token, those users will not be able to complete the flow, and the app won’t be able to connect to their QuickBooks data.
- Applications that do not accept OAuth 2.0 connections will no longer be listed in the Intuit App Stores, such as apps.intuit.com and within QuickBooks Online.
How do I know which type of OAuth my app uses?
See Get Started
for detailed information about how determine whether your apps currently use OAuth 1.0 or OAuth 2.0.
My app still uses OAuth 1.0. What do I need to do?
When and how will migration to OAuth 2.0 affect my existing connections?
As described in the migration documentation, after you release your OAuth 2.0 code changes and update your settings in the developer portal, your new users will connect to QuickBooks using OAuth 2.0 from that point on.
Next, you can start to migrate your existing users (connections) when you are ready, and at your own pace. Here are some options:
- For integrations with many connections: If you support a lot of QuickBooks users, we recommend that you also integrate with the Migration API. This library lets you migrate each user’s token at the desired time, without requiring them to sign in and grant consent again. For example, you can migrate 1000 connections in less than 5 minutes.
- For integrations with a few connections: If your app has a small number of users, and you prefer not to use the Migration API, you can use the Migration tab in the OAuth 2.0 Playground to migrate each connection manually, without requiring your users to sign in again. Note that you will need access to each user’s existing OAuth 1.0 token in order to use this tool.
- For integrations with one connection: If you are your app’s only user, and you prefer not to use the options above, you can simply disconnect your QuickBooks account from your app, and then reconnect by using your new connection flow.
In all cases, be sure that you have updated your application to accept OAuth 2.0 connections before you begin to migrate your users.
Tokens now expire in 1 hour instead of 180 days? How does that affect users?
With OAuth 1.0, you had a access token and access secret for each user. You used these to sign your request and passed it in the Authorization header for every API request on that user’s behalf. These tokens were long-lived, and expired after 180 days. At that point (or shortly before the expiration), you refreshed the tokens using the Reconnect API .
With OAuth 2.0, you have two types of tokens for each user:
- An access token, which you pass in the Authorization header with every API request, such as when you query CompanyInfo. The access token is short-lived, and expires after 1 hour.
- A refresh token, which your app only uses to mint a new access token when the prior one expires. The refresh token can last up to 100 days before it expires, and then the user needs to sign in and grant consent again or you can get a new one programmatically using the Refresh Token API before it expires. Keep in mind that a refresh token is only for getting new (i.e., “refreshing”) access tokens; you can’t pass a refresh token for requests like querying CompanyInfo. Also, the actual value of a refresh token may change more frequently under certain circumstances–but this does not impact how often the user signs in. See Understand Token Expiration for more information.
I migrated all my users, but Intuit says I didn’t. Why?
If you received an email or a status from Intuit Developer that says your app still uses OAuth 1.0, it means our records show that you’ve mostly migrated, but you still have a few active OAuth 1.0 connections.
To complete your migration, you have these choices:
- Migrate your remaining active users to OAuth 2.0. You can either:
- Use the Migration API; or
- Use the Migrate to OAuth 2.0 tab in the OAuth Playground; or
- Ask those users disconnect from your app and reconnect again using your OAuth 2.0 flow.
- For users who no longer actively use your app, you can either:
- Use the Disconnect API to revoke their tokens; or
- Manually disconnect them from within your Intuit Developer account (see below); or
- Ask them to disconnect themselves from their My Apps tab in QuickBooks
To disconnect a user yourself via your Intuit Developer account, you need to know their company’s realm ID (no tokens required).
Go to your app in your developer account, where you see the app’s main dashboard. Scroll down to the cumulative total connections report. Click “Search by Realm ID”. Enter the realm ID in the search box.
The result will show you the realm ID, a Disconnect button, their connection status (active or disconnected), and also the start and expiration dates of their OAuth token. Use the Disconnect button to disable the company’s token for your application. As a best practice, when a user stops using your application, you should promptly discontinue the Processing of their End User Data, in accordance with the Intuit Terms of Service for Intuit Developer Services.