Get started with Microsoft Graph and REST

This article describes the tasks required to get an access token from the Azure AD v2.0 endpoint and call Microsoft Graph using REST calls. It describes the sequence of requests and responses that an app uses to authenticate and retrieve email messages.

First, you need register your app with Azure Active Directory (Azure AD).

Register the application

There are currently two options to register your app with Azure AD.

  • Register an app to use the Azure AD v2.0 endpoint that works for both personal (Microsoft) identities and work and school (Azure AD) accounts.
  • Register an app to use the Azure AD endpoint that supports work and school accounts only.

This article assumes a v2.0 registration, so you'll register your app on the Application Registration Portal. Follow the instructions in Register your Microsoft Graph application with the Azure AD v2.0 endpoint to register your app. For information about using the Azure AD endpoint, see Authenticate using Azure AD.

Some limitations apply when using the v2.0 endpoint. To decide if it's right for you, see Should I use the v2.0 endpoint?

Authenticate the user and get an access token

The app described in this article implements the Authorization Code Grant flow to get access tokens from the Azure AD v2.0 endpoint, following standard OAuth 2.0 protocols. For a complete guide to the flows supported in the Azure AD v2.0 endpoint see Types of the v2.0 endpoint.

With the Authorization Code Grant flow, first you get an authorization code and then you exchange the code for an access token.

Getting an authorization code

The first step in the Authorization Code Grant flow is to get an authorization code. The code is returned to the app by the authorization server when the user signs in and consents to the permissions requested by the app.

You request an authorization code by sending a GET request to the Azure AD v2.0 endpoint. This URL must be opened in a browser so that the user can sign in and provide consent.

Construct the request

1- Start with the base URL:

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize

The tenant segment in the path controls who can sign into the application. Allowed values are common, organizations, consumers, and tenant identifiers. For more information, see Protocol endpoints.

2- Append query parameters to the base URL. These are used to identify the app, the requested permissions, and other auth request information. The following table describes some common parameters.

Parameter Descriptions
client_id The app ID generated by registering the app. This lets Azure AD know which app is requesting the logon.
redirect_uri The location that Azure will redirect to after the user has granted consent to the app. This value must correspond to the value of Redirect URI used when registering the app.
response_type The type of response the app is expecting. This value is code for the Authorization Code Grant flow.
scope A space-separated list of Microsoft Graph permission scopes that the app is requesting. You can also specify OpenId Connect scopes for single sign-on.
state A value included in the request that will also be returned in the token response, used for validation.

For example, the request URL for an application that requires read access to mail might look like the following.

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=<app ID>&redirect_uri=http%3A%2F%2Flocalhost/myapp%2F&response_type=code&state=1234&scope=mail.read

3- Redirect the user to the logon URL. The user is presented with a sign in screen that displays the name of the app. After signing in, the user is presented with the list of the permissions the app requires and prompted to allow or deny. If the user consents, the browser redirects to the redirect URI with the authorization code and state in the query string, as shown in the following example.

http://localhost/myapp/?code=AwABAAAA...cZZ6IgAA&state=1234

The next step is to exchange the authorization code returned for an access token.

Getting an access token

To get an access token, the app posts form-encoded parameters to the token request URL (for example, https://login.microsoftonline.com/common/oauth2/v2.0/token) with the following parameters.

Parameter Descriptions
client_id The app ID generated by registering the app.
client_secret The app secret generated when registering the app.
code The authorization code obtained in the prior step.
redirect_uri This value must be the same as the value used in the authorization code request.
grant_type The type of grant the app is using. This value is code for the Authorization Code Grant flow.
scope A space-separated list of Microsoft Graph permission scopes that the app is requesting.

The request URL for our application, using the code from the previous step, looks like the following.

POST https://login.microsoftonline.com/common/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

{
  grant_type=authorization_code
  &code=AwABAAAA...cZZ6IgAA
  &redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
  &resource=https%3A%2F%2Fgraph.microsoft.com%2F
  &scope=mail.read
  &client\_id=<app ID>
  &client\_secret=<app SECRET>
}

The server responds with a JSON payload which includes the access token.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "token_type":"Bearer",
  "expires_in":"3600",
  "access_token":"eyJ0eXAi...b66LoPVA",
  "scope":"https://graph.microsoft.com/mail.read",
  ...
}

The access token is found in the access_token field of the JSON payload. The app uses this value to set the Authorization header when making REST calls to the API.

Call Microsoft Graph

After the app has an access token, it's ready to call Microsoft Graph. Because this sample app is retrieving messages, it will use an HTTP GET request to the https://graph.microsoft.com/v1.0/me/messages endpoint.

Refine the request

Apps can control the behavior of GET requests by using OData query parameters. We recommend that apps use these parameters to limit the number of results that are returned and to limit the fields that are returned for each item.

This sample app will display messages in a table that shows the subject, sender, and the date and time the message was received. The table displays a maximum of 25 rows and is sorted so that the most recently received message is at the top. The app uses the following query parameters to get these results.

  • $select - Specifies only the subject, sender, and dateTimeReceived fields.
  • $top - Specifies a maximum of 25 items.
  • $orderby - Sorts the results by the dateTimeReceived field.

This results in the following request.

GET https://graph.microsoft.com/v1.0/me/messages?$select=subject,from,receivedDateTime&$top=25&$orderby=receivedDateTime%20DESC
Accept: application/json
Authorization: Bearer eyJ0eXAi...b66LoPVA

Now that you've seen how to make calls to Microsoft Graph, you can use the API reference to construct any other kinds of calls your app needs to make. However, bear in mind that your app needs to have the appropriate permissions configured on the app registration for the calls it makes.

Next steps

See also