openapi: 3.1.0
info:
title: Microsoft Office 365 Microsoft Graph API
description: >-
The Microsoft Graph API provides a unified programmability model to access
data, intelligence, and insights from Microsoft 365, Windows, and Enterprise
Mobility + Security. It serves as the gateway to data and intelligence in
Microsoft 365, enabling applications to interact with users, groups, mail,
calendars, files, and other organizational resources through a single REST
endpoint.
version: 1.0.0
termsOfService: https://docs.microsoft.com/en-us/legal/microsoft-apis/terms-of-use
contact:
name: Microsoft Graph Support
url: https://developer.microsoft.com/en-us/graph/support
license:
name: Microsoft API License
url: https://docs.microsoft.com/en-us/legal/microsoft-apis/terms-of-use
x-documentation:
url: https://learn.microsoft.com/en-us/graph/overview
x-api-explorer:
url: https://developer.microsoft.com/en-us/graph/graph-explorer
servers:
- url: https://graph.microsoft.com/v1.0
description: Microsoft Graph v1.0 production endpoint
- url: https://graph.microsoft.com/beta
description: Microsoft Graph beta endpoint (preview features)
security:
- oauth2: []
- bearerAuth: []
tags:
- name: Calendar
description: >-
Access and manage Outlook calendar events, calendars, and calendar groups.
Supports scheduling, meeting management, and free/busy lookups.
externalDocs:
url: https://learn.microsoft.com/en-us/graph/api/resources/calendar?view=graph-rest-1.0
- name: Groups
description: >-
Manage Microsoft 365 groups and security groups. Groups provide shared
access to resources such as SharePoint sites, shared mailboxes, Planner
plans, OneNote notebooks, and conversations.
externalDocs:
url: https://learn.microsoft.com/en-us/graph/api/resources/group?view=graph-rest-1.0
- name: Mail
description: >-
Access and manage Outlook mail messages, mail folders, and message
attachments. Supports reading, creating, sending, replying, forwarding,
and organizing email.
externalDocs:
url: https://learn.microsoft.com/en-us/graph/api/resources/mail-api-overview?view=graph-rest-1.0
- name: Users
description: >-
Manage users in Azure Active Directory. Users are the core identity
resource representing a person, including their profile, organizational
relationships, and access to services.
externalDocs:
url: https://learn.microsoft.com/en-us/graph/api/resources/user?view=graph-rest-1.0
paths:
# ── Users ──────────────────────────────────────────────────────────────
/users:
get:
operationId: listUsers
summary: Microsoft Office 365 List Users
description: >-
Retrieve a list of user objects. By default, only a limited set of
properties are returned. To return additional properties, use the $select
OData query parameter. Returns up to 100 users per page by default.
Requires User.ReadBasic.All, User.Read.All, or Directory.Read.All
permission.
tags:
- Users
parameters:
- $ref: '#/components/parameters/top'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/select'
- $ref: '#/components/parameters/orderby'
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/expand'
responses:
'200':
description: A collection of user objects.
content:
application/json:
schema:
$ref: '#/components/schemas/UserCollectionResponse'
examples:
Listusers200Example:
summary: Default listUsers 200 response
x-microcks-default: true
value:
'@odata.context': example_value
'@odata.count': 10
'@odata.nextLink': https://www.example.com
value:
- id: abc123
displayName: example_value
givenName: example_value
surname: example_value
mail: example_value
userPrincipalName: example_value
jobTitle: example_value
department: example_value
officeLocation: example_value
companyName: example_value
businessPhones: {}
mobilePhone: example_value
streetAddress: example_value
city: example_value
state: example_value
postalCode: example_value
country: example_value
preferredLanguage: example_value
accountEnabled: true
createdDateTime: '2026-01-15T10:30:00Z'
lastSignInDateTime: '2026-01-15T10:30:00Z'
usageLocation: example_value
identities: {}
assignedLicenses: {}
memberOf: {}
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: createUser
summary: Microsoft Office 365 Create User
description: >-
Create a new user object. The request body must contain the required
properties for the user. You can optionally specify other writable
properties. Requires User.ReadWrite.All or Directory.ReadWrite.All
permission.
tags:
- Users
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserCreateRequest'
examples:
CreateuserRequestExample:
summary: Default createUser request
x-microcks-default: true
value:
accountEnabled: true
displayName: example_value
mailNickname: example_value
userPrincipalName: example_value
passwordProfile:
forceChangePasswordNextSignIn: true
forceChangePasswordNextSignInWithMfa: true
password: example_value
givenName: example_value
surname: example_value
jobTitle: example_value
department: example_value
officeLocation: example_value
mobilePhone: example_value
usageLocation: example_value
responses:
'201':
description: The created user object.
content:
application/json:
schema:
$ref: '#/components/schemas/User'
examples:
Createuser201Example:
summary: Default createUser 201 response
x-microcks-default: true
value:
id: abc123
displayName: example_value
givenName: example_value
surname: example_value
mail: example_value
userPrincipalName: example_value
jobTitle: example_value
department: example_value
officeLocation: example_value
companyName: example_value
businessPhones:
- example_value
mobilePhone: example_value
streetAddress: example_value
city: example_value
state: example_value
postalCode: example_value
country: example_value
preferredLanguage: example_value
accountEnabled: true
createdDateTime: '2026-01-15T10:30:00Z'
lastSignInDateTime: '2026-01-15T10:30:00Z'
usageLocation: example_value
passwordProfile:
forceChangePasswordNextSignIn: true
forceChangePasswordNextSignInWithMfa: true
password: example_value
identities:
- signInType: example_value
issuer: example_value
issuerAssignedId: '500123'
assignedLicenses:
- disabledPlans: {}
skuId: '500123'
manager:
'@odata.type': example_value
id: abc123
displayName: example_value
memberOf:
- '@odata.type': example_value
id: abc123
displayName: example_value
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/users/{user-id}:
get:
operationId: getUser
summary: Microsoft Office 365 Get User
description: >-
Retrieve the properties and relationships of a user object. Returns a
limited set of properties by default; use $select to request additional
properties. Requires User.Read, User.ReadBasic.All, User.Read.All, or
Directory.Read.All permission.
tags:
- Users
parameters:
- $ref: '#/components/parameters/userId'
- $ref: '#/components/parameters/select'
- $ref: '#/components/parameters/expand'
responses:
'200':
description: The requested user object.
content:
application/json:
schema:
$ref: '#/components/schemas/User'
examples:
Getuser200Example:
summary: Default getUser 200 response
x-microcks-default: true
value:
id: abc123
displayName: example_value
givenName: example_value
surname: example_value
mail: example_value
userPrincipalName: example_value
jobTitle: example_value
department: example_value
officeLocation: example_value
companyName: example_value
businessPhones:
- example_value
mobilePhone: example_value
streetAddress: example_value
city: example_value
state: example_value
postalCode: example_value
country: example_value
preferredLanguage: example_value
accountEnabled: true
createdDateTime: '2026-01-15T10:30:00Z'
lastSignInDateTime: '2026-01-15T10:30:00Z'
usageLocation: example_value
passwordProfile:
forceChangePasswordNextSignIn: true
forceChangePasswordNextSignInWithMfa: true
password: example_value
identities:
- signInType: example_value
issuer: example_value
issuerAssignedId: '500123'
assignedLicenses:
- disabledPlans: {}
skuId: '500123'
manager:
'@odata.type': example_value
id: abc123
displayName: example_value
memberOf:
- '@odata.type': example_value
id: abc123
displayName: example_value
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
patch:
operationId: updateUser
summary: Microsoft Office 365 Update User
description: >-
Update the properties of a user object. Not all properties can be
updated by Member or Guest users with their default permissions without
administrator roles. Requires User.ReadWrite, User.ReadWrite.All, or
Directory.ReadWrite.All permission.
tags:
- Users
parameters:
- $ref: '#/components/parameters/userId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserUpdateRequest'
examples:
UpdateuserRequestExample:
summary: Default updateUser request
x-microcks-default: true
value:
displayName: example_value
givenName: example_value
surname: example_value
jobTitle: example_value
department: example_value
officeLocation: example_value
mobilePhone: example_value
businessPhones:
- example_value
streetAddress: example_value
city: example_value
state: example_value
postalCode: example_value
country: example_value
preferredLanguage: example_value
accountEnabled: true
usageLocation: example_value
passwordProfile:
forceChangePasswordNextSignIn: true
forceChangePasswordNextSignInWithMfa: true
password: example_value
responses:
'204':
description: User updated successfully. No content returned.
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
operationId: deleteUser
summary: Microsoft Office 365 Delete User
description: >-
Delete a user object. When deleted, user resources are moved to a
temporary container and can be restored within 30 days. After 30 days,
they are permanently deleted. Requires User.ReadWrite.All or
Directory.ReadWrite.All permission.
tags:
- Users
parameters:
- $ref: '#/components/parameters/userId'
responses:
'204':
description: User deleted successfully. No content returned.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/me:
get:
operationId: getSignedInUser
summary: Microsoft Office 365 Get Signed-in User
description: >-
Retrieve the properties and relationships of the currently signed-in
user. The /me endpoint resolves to the signed-in user based on the
access token. Requires User.Read permission at minimum.
tags:
- Users
parameters:
- $ref: '#/components/parameters/select'
- $ref: '#/components/parameters/expand'
responses:
'200':
description: The signed-in user object.
content:
application/json:
schema:
$ref: '#/components/schemas/User'
examples:
Getsignedinuser200Example:
summary: Default getSignedInUser 200 response
x-microcks-default: true
value:
id: abc123
displayName: example_value
givenName: example_value
surname: example_value
mail: example_value
userPrincipalName: example_value
jobTitle: example_value
department: example_value
officeLocation: example_value
companyName: example_value
businessPhones:
- example_value
mobilePhone: example_value
streetAddress: example_value
city: example_value
state: example_value
postalCode: example_value
country: example_value
preferredLanguage: example_value
accountEnabled: true
createdDateTime: '2026-01-15T10:30:00Z'
lastSignInDateTime: '2026-01-15T10:30:00Z'
usageLocation: example_value
passwordProfile:
forceChangePasswordNextSignIn: true
forceChangePasswordNextSignInWithMfa: true
password: example_value
identities:
- signInType: example_value
issuer: example_value
issuerAssignedId: '500123'
assignedLicenses:
- disabledPlans: {}
skuId: '500123'
manager:
'@odata.type': example_value
id: abc123
displayName: example_value
memberOf:
- '@odata.type': example_value
id: abc123
displayName: example_value
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
# ── Groups ─────────────────────────────────────────────────────────────
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/groups:
get:
operationId: listGroups
summary: Microsoft Office 365 List Groups
description: >-
List all groups in an organization, including Microsoft 365 groups,
security groups, and distribution groups. Returns up to 100 objects
by default. To return additional properties, use $select. Requires
GroupMember.Read.All, Group.Read.All, or Directory.Read.All permission.
tags:
- Groups
parameters:
- $ref: '#/components/parameters/top'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/select'
- $ref: '#/components/parameters/orderby'
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/expand'
responses:
'200':
description: A collection of group objects.
content:
application/json:
schema:
$ref: '#/components/schemas/GroupCollectionResponse'
examples:
Listgroups200Example:
summary: Default listGroups 200 response
x-microcks-default: true
value:
'@odata.context': example_value
'@odata.count': 10
'@odata.nextLink': https://www.example.com
value:
- id: abc123
displayName: example_value
description: A sample description.
mail: example_value
mailEnabled: true
mailNickname: example_value
securityEnabled: true
groupTypes: {}
visibility: Public
createdDateTime: '2026-01-15T10:30:00Z'
renewedDateTime: '2026-01-15T10:30:00Z'
classification: example_value
membershipRule: example_value
membershipRuleProcessingState: 'On'
resourceProvisioningOptions: {}
members: {}
owners: {}
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: createGroup
summary: Microsoft Office 365 Create Group
description: >-
Create a new Microsoft 365 group or security group. You can create
Microsoft 365 groups with a team, a channel, or both by specifying the
resourceProvisioningOptions. Requires Group.ReadWrite.All or
Directory.ReadWrite.All permission.
tags:
- Groups
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GroupCreateRequest'
examples:
CreategroupRequestExample:
summary: Default createGroup request
x-microcks-default: true
value:
displayName: example_value
description: A sample description.
mailEnabled: true
mailNickname: example_value
securityEnabled: true
groupTypes:
- example_value
visibility: Public
'[email protected]':
- example_value
'[email protected]':
- example_value
responses:
'201':
description: The created group object.
content:
application/json:
schema:
$ref: '#/components/schemas/Group'
examples:
Creategroup201Example:
summary: Default createGroup 201 response
x-microcks-default: true
value:
id: abc123
displayName: example_value
description: A sample description.
mail: example_value
mailEnabled: true
mailNickname: example_value
securityEnabled: true
groupTypes:
- example_value
visibility: Public
createdDateTime: '2026-01-15T10:30:00Z'
renewedDateTime: '2026-01-15T10:30:00Z'
classification: example_value
membershipRule: example_value
membershipRuleProcessingState: 'On'
resourceProvisioningOptions:
- example_value
members:
- '@odata.type': example_value
id: abc123
displayName: example_value
owners:
- '@odata.type': example_value
id: abc123
displayName: example_value
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/groups/{group-id}:
get:
operationId: getGroup
summary: Microsoft Office 365 Get Group
description: >-
Get the properties and relationships of a group object. Returns a
default set of properties; use $select to request additional properties.
Requires GroupMember.Read.All, Group.Read.All, or Directory.Read.All
permission.
tags:
- Groups
parameters:
- $ref: '#/components/parameters/groupId'
- $ref: '#/components/parameters/select'
- $ref: '#/components/parameters/expand'
responses:
'200':
description: The requested group object.
content:
application/json:
schema:
$ref: '#/components/schemas/Group'
examples:
Getgroup200Example:
summary: Default getGroup 200 response
x-microcks-default: true
value:
id: abc123
displayName: example_value
description: A sample description.
mail: example_value
mailEnabled: true
mailNickname: example_value
securityEnabled: true
groupTypes:
- example_value
visibility: Public
createdDateTime: '2026-01-15T10:30:00Z'
renewedDateTime: '2026-01-15T10:30:00Z'
classification: example_value
membershipRule: example_value
membershipRuleProcessingState: 'On'
resourceProvisioningOptions:
- example_value
members:
- '@odata.type': example_value
id: abc123
displayName: example_value
owners:
- '@odata.type': example_value
id: abc123
displayName: example_value
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
patch:
operationId: updateGroup
summary: Microsoft Office 365 Update Group
description: >-
Update the properties of a group object. Requires Group.ReadWrite.All
or Directory.ReadWrite.All permission. Not every property can be updated.
tags:
- Groups
parameters:
- $ref: '#/components/parameters/groupId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GroupUpdateRequest'
examples:
UpdategroupRequestExample:
summary: Default updateGroup request
x-microcks-default: true
value:
displayName: example_value
description: A sample description.
mailNickname: example_value
visibility: Public
classification: example_value
responses:
'204':
description: Group updated successfully. No content returned.
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
operationId: deleteGroup
summary: Microsoft Office 365 Delete Group
description: >-
Delete a group. When deleted, Microsoft 365 groups are moved to a
temporary container and can be restored within 30 days. Security
groups and distribution groups are permanently deleted immediately.
Requires Group.ReadWrite.All or Directory.ReadWrite.All permission.
tags:
- Groups
parameters:
- $ref: '#/components/parameters/groupId'
responses:
'204':
description: Group deleted successfully. No content returned.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/groups/{group-id}/members:
get:
operationId: listGroupMembers
summary: Microsoft Office 365 List Group Members
description: >-
Get a list of the group's direct members. A group can have users,
organizational contacts, devices, service principals, and other groups
as members. Requires GroupMember.Read.All, Group.Read.All, or
Directory.Read.All permission.
tags:
- Groups
parameters:
- $ref: '#/components/parameters/groupId'
- $ref: '#/components/parameters/top'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/select'
- $ref: '#/components/parameters/count'
responses:
'200':
description: A collection of directory objects representing group members.
content:
application/json:
schema:
$ref: '#/components/schemas/DirectoryObjectCollectionResponse'
examples:
Listgroupmembers200Example:
summary: Default listGroupMembers 200 response
x-microcks-default: true
value:
'@odata.context': example_value
'@odata.count': 10
'@odata.nextLink': https://www.example.com
value:
- '@odata.type': example_value
id: abc123
displayName: example_value
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/groups/{group-id}/members/$ref:
post:
operationId: addGroupMember
summary: Microsoft Office 365 Add Group Member
description: >-
Add a member to a Microsoft 365 group or a security group through the
members navigation property. You can add users, organizational contacts,
service principals, or other groups. Requires GroupMember.ReadWrite.All,
Group.ReadWrite.All, or Directory.ReadWrite.All permission.
tags:
- Groups
parameters:
- $ref: '#/components/parameters/groupId'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- '@odata.id'
properties:
'@odata.id':
type: string
description: >-
The URL of the directory object to add as a member.
example: https://graph.microsoft.com/v1.0/directoryObjects/{id}
examples:
AddgroupmemberRequestExample:
# --- truncated at 32 KB (136 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/microsoft-office-365/refs/heads/main/openapi/microsoft-graph-api-openapi.yml