If you’ve already implemented OAuth 2.0, but you’re still using OAuth 1.0 tokens for existing users, it usually only takes 1 to 2 hours to migrate those tokens to OAuth 2.0.
Before you take this step, be sure that you’ve already updated your application to accept OAuth 2.0 connections.
Scalable approach: Use the migration API
You can make the migration process transparent to users by using the Migration API, so that your existing users don’t need to grant consent again to connect your app to QuickBooks.
If you support a lot of QuickBooks users, you can write a script (or a very simple app) to migrate tokens in bulk. For example, the Migration API can migrate 1,000 connections in less than 5 minutes.
We offer several client libraries for the Migration API, including Java, PHP, .NET, Node.js, Python, and Ruby. We also offer a number of migration code samples.
Manual approach: Use the OAuth migration playground
If you support only a few users, and if you’d prefer not to write code to use the Migration API directly, you can use the Migration tab in the OAuth Playground to migrate each connection one at a time. This still migrates their tokens without requiring each user to reconnect your app to their QuickBooks account. Note that you will still need each user’s existing OAuth 1.0 token in order to use this tool.
User assisted approach: Disconnect/Reconnect the user
If your app only has one user (e.g., yourself) and/or you prefer not to migrate a connection using one of the options above, you can instead force the OAuth 1.0 token(s) to fully expire by disconnecting the QuickBooks company account (realm) from your app. After that, you’ll need to ask the user(s) to reconnect to QuickBooks Online via your new OAuth 2.0 connection flow to get an OAuth 2.0 token.
Note that with this approach you are not migrating an existing token to OAuth 2.0; you’re creating a new OAuth 2.0 token. That means you must also disconnect all existing (old) OAuth 1.0 tokens, in order for Intuit to recognize that your connections are fully migrated off of OAuth 1.0.
Here are several ways to disconnect an OAuth 1.0 token:
Option a: Use the Disconnect API: As long as you have a user’s OAuth 1.0 token, you can revoke it by using the Disconnect API. If you have a strong GDPR compliance process in place already, then your system might already support the Disconnect API.
If you no longer store a user’s OAuth 1.0 token in your system, you have two additional options:
Option b: Ask the user to disconnect your app from their My Apps tab within QuickBooks Online.
Option c: Disconnect via Your Developer Dashboard: You can disconnect companies manually by using the monthly connection reports on developer.intuit.com. If you identify an active (not expired) realm ID that you need to disconnect, use the red Disconnect button to manually disconnect that realm from your app, as shown below.
What’s next?
After you migrate (or permanently disconnect) all your OAuth 1.0 connections, visit your OAuth Migration Mission and check off “Migrate OAuth 1.0 access tokens to OAuth 2.0” to track your progress.
Note: This OAuth Migration mission and offer is for developers whose apps still use OAuth 1.0 for QuickBooks Online accounting and payments API calls. As a reminder, you must migrate to OAuth 2.0 by Dec. 17, 2019 at the latest. We strongly recommend you plan to migrate sooner.
You’ll also get 250 points after you fully complete your migration.
Troubleshooting: I think I’m done, but The Bridge says I’m not
If you migrated all your users, but your Migrate from OAuth 1.0 mission shows that your app still has connections that are using OAuth 1.0, here are a few common situations to check:
- Has a user signed in again using your previous OAuth 1.0 flow?
- Did a user unsubscribe from your app in the past, and you didn’t revoke (disconnect) their token?
- Did you create an entirely new app (with a different AppID) on developer.intuit.com for your OAuth 2.0 implementation, and you didn’t disconnect OAuth 1.0 tokens for the original app?
- Has it been less than 2 days since you finished migrating all your users? (If so, come back in a day or two and check again.)
As always, please feel free to ask questions about OAuth migration in our OAuth help community!
Leave a Reply