As you might know, we have a new v2 auth model that supports sign-on and access to Microsoft Graph and Outlook APIs for consumer, work, and school accounts. In case you missed it, here is the v2 auth model GA announcement and here is the link to the new v2 auth model protocol specs.

Together with the Outlook APIs that work for both Office 365 and Outlook.com users that have been upgraded to Office 365, this gives a very powerful story for those of you who are developing apps. When I say Outlook.com users, this also includes all other domains supported in Outlook.com such as Hotmail.com, msn.com, Live.com and so on.

The fantastic story: One single Auth and API model for both the consumers and business users!

Before the v2 app model came along, this story was not always so nice. So, I want to write about how you might get to the new fantastic story. Especially if you have an existing application that works against Outlook.com using the Live Connect APIs, Exchange Active Sync (EAS), or IMAP, and use the Live OAuth2 protocol, this blog will be of interest for you. You can use this as a starting point to transition your app from using Live APIs to using Outlook REST APIs.

First of all, there is no need to worry that your existing application will break, even if an Outlook.com user is upgraded to Office 365. IMAP and EAS protocols continue to work the same way as it worked before the upgrade.

Now, let’s think about a possible transition. I broke the migration down to three stages as my simple mind has trouble remembering more than 3 distinct steps or stages :-).

Stage 1: Leave it as it is – no benefit but it just continues to work

“Doh!” you might say, but it’s always good to ensure a starting point that requires no changes and understand its impact. In this stage, your application uses the LiveID OAuth2 protocol and Live APIs to run against Outlook.com mailboxes. Your application will continue to run fine even if the mailbox of the user hasn’t yet been upgraded to Office 365.

So what’s the downside? Your application continues to work. However, once mailboxes are migrated to Office 365 you can’t take advantage of all the rich features Office 365 provides today and plans to provide in the future. You’re literally stuck with the existing functionality while all innovations in Office 365 will be out of reach for your application. You’re also not able to access work or school accounts.

Stage 2: Switch the API – benefit from new Office 365 features

Now, as soon as an Outlook.com user is upgraded to Office 365, you have more options with v2 Auth model, and Outlook REST APIs. You are not constrained by the limitations of the Live SDK and can take advantage of Office 365 innovations and additional services and functionalities.

This all happens in what I call “Stage 2”. In this stage, your application continues to work for Outlook.com mailboxes like before, but you start to integrate with the Outlook REST APIs for migrated mailboxes. As part of this integration, you don’t need to change the authentication protocol. Your users will not be prompted again for consent, even when they are upgraded to Office 365 (unless of course you extend your app beyond existing functionality that might require more permissions).

Take a look at the table below, it shows how the LiveID OAuth2 scopes map to the new Outlook REST API scopes that are listed in Outlook API documentation.

The general pattern in this stage is that your application tries to first access the mailbox using the Outlook REST APIs. In case the user hasn’t yet been upgraded to Office 365, Outlook REST APIs will return a very specific message back to your application as a signal to use the Live APIs:

• Http Error: 404
• Error code: MailboxNotEnabledForRESTAPI
• Error message: “REST API is not yet enabled for this mailbox.”

OR

• Http Error: 404
• Error code: MailboxNotSupportedForRESTAPI
• Error message: “REST API is not yet supported for this mailbox.”

To summarize this stage was all about starting and taking advantage of the new Outlook Rest APIs, while continuing to support Outlook.com users who haven’t yet been upgraded to Office 365. However, so far your application is still bound to the consumer world. The opportunity of reaching tens of millions of business users in Office 365 is just one step away.

Stage 3: Switch the Auth model – Unleash your application to reach new horizons

In this final stage, you switch your application from using LiveID OAuth2 protocol to the new v2 Auth model OAuth2 protocol.

Now, there is a caveat: When you do this, your consumer users will be re-prompted for consent, as only the Outlook REST API scopes apply to consumer and business accounts.

However, this might be a small price to pay considering your application is now ready to transparently target Office 365 users, in addition to the users you are already servicing.

After you’re done with this stage, you arrived at the point where your application can work the same way for consumer and business mailboxes, and it is also ready to take advantage of new capabilities of Office 365. It can even start integrating with the Microsoft Graph to integrate with OneDrive or other Office 365 services. The possibilities to build a much better and richer application and make it available to all Office 365 users is very exciting…in my opinion. 🙂

With this said, I hope I gave a good starting point about how you can transform your application to Office 365. A big thank you for reading and as always, feedback, questions, etc. are very much appreciated!

Please use Stack Overflow for questions, and be sure to tag your post with outlook-restapi or MicrosoftGraph.

And as always, visit https://developer.microsoft.com/en-us/outlook/ for the latest and greatest news, updates, samples and reference materials on our Outlook APIs.

Thank you! Matthias Leibmann