Microsoft Graph Getting Started: Setup and First Request (2026)

Getting started overview

To begin integrating with Microsoft Graph, developers need to establish an environment that allows authenticated access to Microsoft 365 data. This typically involves several steps: ensuring access to a Microsoft 365 tenant, registering an application within Azure Active Directory (Azure AD), configuring appropriate API permissions, and then implementing an authentication flow to obtain an access token. This token is subsequently used to authorize requests made to the Microsoft Graph API endpoints.

Microsoft Graph provides a unified endpoint, https://graph.microsoft.com, to access data and intelligence from Microsoft 365 services, Windows 365, and Microsoft Intune. The API is RESTful and supports JSON for data exchange. While direct HTTP calls are possible, Microsoft offers client libraries (SDKs) for various programming languages to simplify interactions and handle authentication mechanisms. For a comprehensive overview of the API, consult the Microsoft Graph API reference.

The following table outlines the foundational steps required to get started:

Create an account and get keys

Access to Microsoft Graph relies on an Azure Active Directory (Azure AD) tenant. If you do not already have a Microsoft 365 subscription or an Azure AD tenant, you can obtain one through the Microsoft 365 Developer Program. This program provides a free, renewable Microsoft 365 E5 developer subscription with pre-provisioned data, including users and mailboxes, which is suitable for testing Microsoft Graph applications.

Registering your application

Once you have access to a tenant, the next step is to register your application within Azure AD. This registration process assigns a unique Application (client) ID to your application, which is crucial for authentication. Follow these steps:

1. Navigate to the Azure portal.
2. Search for and select Azure Active Directory.
3. In the left-hand menu, select App registrations, then New registration.
4. Provide a name for your application.
5. Choose the supported account types (e.g., 'Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)').
6. For web applications, specify a Redirect URI. For desktop or mobile apps, you may not need one initially, or you can use a placeholder like http://localhost.
7. Click Register.

After registration, you will be directed to the application's overview page. Here, note down the Application (client) ID and Directory (tenant) ID. These identifiers are essential for configuring your authentication requests. Additionally, for applications requiring client secrets (e.g., web apps, daemons), navigate to Certificates & secrets, click New client secret, provide a description, and note the generated secret value immediately as it will not be displayed again.

Configuring API permissions

Your application needs explicit permission to access specific types of data through Microsoft Graph. These permissions are configured in the Azure portal:

1. From your application's overview page in Azure AD, select API permissions from the left-hand menu.
2. Click Add a permission.
3. Select Microsoft Graph under the Microsoft APIs tab.
4. Choose the type of permissions required:
• Delegated permissions: For applications acting on behalf of a signed-in user.
• Application permissions: For applications running without a signed-in user (daemon apps).
5. Select the specific permissions your application needs (e.g., User.Read to read user profiles, Mail.Read to read user mail). For a first request, User.Read.All (application permission) or User.Read (delegated permission) are common starting points.
6. Click Add permissions.
7. For application permissions, or if administrators need to consent to delegated permissions for all users in their organization, an administrator must click Grant admin consent for [your tenant].

For more details on required permissions for specific API calls, refer to the Microsoft Graph permissions reference.

Your first request

After setting up your application and permissions, the next step is to obtain an access token and make your first call. This example will use the OAuth 2.0 Client Credentials flow for simplicity, suitable for daemon or background services, requesting an access token directly using client ID and secret. For user-interactive applications, the Authorization Code flow or Implicit Grant flow would be used.

1. Obtain an Access Token (Client Credentials Flow)

To get an access token, send a POST request to the Azure AD token endpoint. Replace {tenant-id}, {client-id}, and {client-secret} with your application's details.

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

client_id={client_id}
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_secret={client_secret}
&grant_type=client_credentials

A successful response will include an access_token, which is a JSON Web Token (JWT). This token needs to be included in the Authorization header of your Microsoft Graph API requests.

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "ext_expires_in": 3600,
  "access_token": "eyJ0eXAiOiJKV1Qi..." 
}

2. Make a Microsoft Graph API call

With the access token, you can now make a call to Microsoft Graph. A common first request is to retrieve information about the tenant's users or your own profile.

GET https://graph.microsoft.com/v1.0/users
Authorization: Bearer {access_token}
Content-Type: application/json

This request retrieves a list of users in your tenant. If you configured User.Read (delegated permission) and signed in as a user, you could query https://graph.microsoft.com/v1.0/me to get the signed-in user's profile. Ensure the permissions granted during application registration align with the API endpoint you are calling.

A successful response would look like this (abbreviated):

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users",
  "value": [
    {
      "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "displayName": "Nestor Wilke",
      "mail": "[email protected]",
      // ... other user properties
    }
  ]
}

Common next steps

After successfully making your first request, consider these common next steps:

• Explore SDKs: Microsoft Graph offers SDKs for .NET, Go, Java, JavaScript, PHP, PowerShell, Python, and Ruby. These SDKs abstract away the HTTP calls and token management, simplifying development.
• Implement Webhooks: For real-time notifications about changes in Microsoft 365 data (e.g., new emails, calendar events), implement webhooks. This is more efficient than polling the API. Learn about Microsoft Graph webhooks.
• Advanced Queries: Explore OData query parameters for filtering, sorting, and pagination of results. This allows for more precise data retrieval. The Microsoft Graph documentation on query parameters provides examples.
• Integrate with other Microsoft Services: Beyond basic user data, explore integrating with specific services like Outlook (mail, calendar), OneDrive (files), or Teams (chats, calls).
• Secure Production Applications: Review security best practices for production applications, including token caching, secure client secret storage, and proper error handling. Refer to Microsoft Graph security best practices.
• Explore Graph Explorer: Use the Graph Explorer tool provided by Microsoft to test API calls directly in the browser. It allows you to sign in with your Microsoft account, make requests, and see responses without writing code.
• Understand OAuth 2.0 flows: Depending on your application type (web, mobile, desktop, daemon), you will use different OAuth 2.0 flows. A deeper understanding of these flows, as described in the OAuth 2.0 specification, is beneficial for building robust applications.

Troubleshooting the first call

Several common issues can arise when making your first Microsoft Graph API call:

• Invalid or Expired Access Token: Ensure your access token is current and correctly included in the Authorization: Bearer {token} header. Tokens have a limited lifespan (typically 1 hour) and must be refreshed.
• Incorrect Permissions: The most frequent issue. Double-check that your registered application has been granted the specific Microsoft Graph permissions required by the API endpoint you are calling (e.g., User.Read.All for listing all users, Mail.Read for reading email). Also, verify if admin consent is needed and has been granted. Review the Microsoft Graph permissions reference carefully.
• Tenant ID or Client ID Mismatch: Confirm that the tenant ID and client ID used in your token request match those of your registered application.
• Client Secret Issues: For client credentials flow, ensure the client secret is correct and has not expired. If it's expired, generate a new one in the Azure portal. Remember to copy the secret immediately after generation.
• Incorrect Endpoint URL: Ensure the Microsoft Graph endpoint URL is correct (e.g., https://graph.microsoft.com/v1.0/me or https://graph.microsoft.com/v1.0/users). Incorrect versions (e.g., beta vs. v1.0) or typos will lead to errors.
• Network or Firewall Issues: Verify that your development environment can reach login.microsoftonline.com and graph.microsoft.com.
• HTTP Status Codes:
• 401 Unauthorized: Typically indicates an issue with the access token (missing, invalid, or expired).
• 403 Forbidden: Usually means the application lacks the necessary permissions to perform the requested operation, even if the token is valid.
• 404 Not Found: Often due to an incorrect API endpoint URL or an object that does not exist.
• Using Graph Explorer: If you're encountering issues, try replicating the call in Graph Explorer. This tool simplifies testing and helps identify if the problem is with your code, permissions, or the API itself.