Introduction to the Graph API

Welcome to the Microsoft Graph API documentation. This API provides a unified programming model that you can use to access data and insights from Microsoft 365. With a single endpoint, https://graph.microsoft.com, you can access resources across Microsoft Graph, including Office 365, Windows, and Enterprise Mobility + Security.

This reference documentation details the available APIs, their parameters, request and response formats, and common usage scenarios.

Authentication and Authorization

Microsoft Graph uses Azure Active Directory (Azure AD) to authenticate requests and grant access to resources. You can obtain an access token from Azure AD and include it in the Authorization header of your requests.

Common authentication flows include:

For detailed information on setting up authentication, please refer to the Microsoft Identity Platform documentation.

API Endpoints

The base URL for all Microsoft Graph API requests is: https://graph.microsoft.com/{version}/

The current stable version is v1.0.

Users

This section covers operations related to user resources.

GET https://graph.microsoft.com/v1.0/users/{id | userPrincipalName}

Retrieves the properties of a specified user.

Parameters:

Name Type Description Required
id | userPrincipalName String The object ID or User Principal Name (UPN) of the user. Yes
$select String Comma-separated list of properties to retrieve. No
$expand String Comma-separated list of navigation properties to expand. No
GET https://graph.microsoft.com/v1.0/users

Retrieves a list of user objects.

Query Parameters:

Name Type Description Required
$filter String Filter results using OData filter syntax. No
$top Integer Maximum number of results to return. No
POST https://graph.microsoft.com/v1.0/users

Create a new user.

Request Body:

{
  "accountEnabled": true,
  "displayName": "Jane Doe",
  "mailNickname": "jane",
  "userPrincipalName": "jane.doe@contoso.com",
  "passwordProfile": {
    "forceChangePasswordNextSignIn": true,
    "password": "MyStrongPassword123!"
  }
}

Groups

Manage and access information about Microsoft 365 groups.

GET https://graph.microsoft.com/v1.0/groups/{id}

Retrieve a specific group.

Devices

Information and management of devices in your organization.

GET https://graph.microsoft.com/v1.0/devices

List devices.

Error Handling

When an error occurs, the Graph API returns an error response with a standard structure. The response typically includes an error code, a user-friendly message, and often detailed error information.

Example error response: 

{
  "error": {
    "code": "BadRequest",
    "message": "Invalid request parameter.",
    "innerError": {
      "request-id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "date": "2023-10-27T10:30:00Z"
    }
  }
}

Refer to the Graph API error documentation for a comprehensive list of error codes.

Key Concepts