Understanding the Office 365 Discovery Service API Flow

Scot Hillier

by Scot Hillier on 10/7/2014

Share this:

Article Details

Date Revised:

UPDATE: Since this article was written, the Discovery Service has moved out of preview.

The Discovery Service now supports version endpoints.

Preview: https://api.office.com/discovery/me (OData v3)
Release: https://api.office.com/discovery/v1.0/me (OData v4)


As more people and organizations move into the cloud, developers will increasingly write applications that leverage the rich store of contacts, mail, events, and documents that are available through the Office 365 APIs. Because Office 365 contains many tenancies, however, it can be a challenge to locate the proper REST endpoint for the person using an application. The Discovery Service allows developers to find these endpoints dynamically, which simplifies the task of writing an application that works across tenancies.

While the Office 365 APIs do a good job of abstracting away the complexities of using the Discovery Service, it’s still important for developers to understand what’s going on under the covers. In this article, I’ll take a look at how the Discovery Service flow works so you can better understand its role in an Office 365 application.

The scenario I’ll use for the article involves reading the files from the current user’s OneDrive for Business library in Office 365. The OneDrive for Business library is available in SharePoint Online by clicking the OneDrive link in the header. This will take you to a special Document Library within your Personal Site.


Figure 1, Linking to OneDrive for Business


Figure 2, The OneDrive for Business Library



In order to get started with the Discovery Service, you first need to know whether you are dealing with a Microsoft Account or an Organizational Account. The FirstSignIn API forces the user to a login page to enter their account and then returns the endpoints you’ll need to continue working with the Discovery Service. You can see how the FirstSignIn API works by starting Fiddler and clicking the following link.


You will be asked to provide your account name and then redirected to the Microsoft site. Normally, the redirection would be to your application, but this makes it easy to see what is happening. When you arrive at the Microsoft site, examine the session in Fiddler and you’ll see that endpoint information was returned for your account.


Figure 3, Return value from FirstSignin



The next step in the discovery process is to get an Access Token using the authorization service endpoint returned by the FirstSignIn API. The authorization URL requires you to provide the Client Id of the application that will be accessing the OneDrive for Business files as well as a Redirect Uri to launch after authentication completes. The following URL shows a sample.


The authorization URL will force the user to sign in and then return an Authorization Code as a query string parameter. The following shows a sample of the resulting URL.


Once you have an Authorization Code, you can POST that Authorization Code to the token service endpoint. In the body of the POST, you must also provide some other key information (shown below), and you will get an Access Token and Refresh Token in return. The following is the URL provided by the FirstSignIn response:



Figure 4, Required POST Parameters


Figure 5, Returned Access and Refresh Tokens



Once you have an Access Token, you can finally call to the Discovery Service and get the endpoint for the current user. The Discovery Service is a simple GET request to the endpoint returned by the FirstSignIn call.


The return value is a JSON object with information about the service endpoints. For the OneDrive for Business library, the endpoint will refer to the user’s Personal Site and the MyFiles capability as shown below.


Figure 6, Returned Endpoint Information

Once you have the proper endpoint, you can then make subsequent REST calls to perform CRUD operations.


The Discovery Service allows you to find the service endpoints for contacts, events, e-mail, and documents for the current user. In order to use it you must follow a sequence of events designed to authorize the application and discover the endpoints. This flow can be summarized as:

  1. Call FirstSignIn endpoint

  2. Retrieve authorization, token, and discovery endpoints

  3. Call the authorization endpoint

  4. Retrieve an Authorization Code

  5. Call the token endpoint

  6. Retrieve an Access Token

  7. Call the discovery endpoint

  8. Retrieve service endpoints for mail, calendar, contacts, or documents

  9. Make subsequent REST calls to the service endpoints to perform CRUD operations





Topic: Development

Sign in with

Or register