Table of contents

Entity and complex type reference | Graph API reference

Bryan Lamos|Last Updated: 6/27/2018
|
7 Contributors

Applies to: Graph API | Azure Active Directory

This topic discusses the entities and complex types that are exposed by the Graph API.

The Graph API is an OData 3.0 compliant REST API that provides programmatic access to directory objects in Azure Active Directory, such as users, groups, organizational contacts, and applications.

Important

We strongly recommend that you use Microsoft Graph instead of Azure AD Graph API to access Azure Active Directory resources. Our development efforts are now concentrated on Microsoft Graph and no further enhancements are planned for Azure AD Graph API. There are a very limited number of scenarios for which Azure AD Graph API might still be appropriate; for more information, see the Microsoft Graph or the Azure AD Graph blog post in the Office Dev Center.

Entity reference

Application Entity

Represents an application. Any application that outsources authentication to Azure AD must be registered in a directory. This involves telling Azure AD about your application, including the URL where it's located, the URL to send replies after authentication, the URI to identify your application, and more. For more information, see Basics of Registering an Application in Azure AD. Inherits from DirectoryObject.

Properties

Declared Properties

NameTypeSupportsDescription
addInsCollection(AddIn)POST, GET, PATCHDefines custom behavior that a consuming service can use to call an app in specific contexts. For example, applications that can render file streams may set the addIns property for its "FileHandler" functionality. This will let services like Office 365 call the application in the context of a document the user is working on.

Notes: Requires version 1.6.
appIdEdm.String in version 1.5

Edm.Guid in previous versions
GET ($filter)The unique identifier for the application.
appRolesCollection(AppRole)POST, GET, PATCHThe collection of application roles that an application may declare. These roles can be assigned to users, groups or service principals.

Notes: Requires version 1.5, not nullable.
availableToOtherTenantsEdm.BooleanPOST, GET ($filter), PATCHtrue if the application is shared with other tenants; otherwise, false.
deletionTimestampEdm.DateTimeGETThe time at which the application was deleted from the tenant. If the application has not been deleted, returns null. Deleted applications can be read from the /deletedApplications resource collection. Inherited from DirectoryObject.

Notes: Requires version 1.5 or newer.
displayNameEdm.StringPOST (Required), GET, PATCHThe display name for the application.
errorUrlEdm.StringPOST, GET, PATCH
groupMembershipClaimsEdm.StringPOST, GET, PATCHA bitmask that configures the "groups" claim issued in a user or OAuth 2.0 access token that the application expects. The bitmask values are: 0: None, 1: Security groups and Azure AD roles, 2: Reserved, and 4: Reserved. Setting the bitmask to 7 will get all of the security groups, distribution groups, and Azure AD directory roles that the signed-in user is a member of.

Notes: Requires version 1.5.
homepageEdm.StringPOST, GET, PATCHThe URL to the application's homepage.
identifierUrisCollection(Edm.String)POST, GET ($filter), PATCHUser-defined URI(s) that uniquely identify a Web application within its Azure AD tenant, or within a verified custom domain (see "Domains" tab in the Azure classic portal) if the application is multi-tenant.

The first element is populated from the Web application's "APP ID URI” field if updated via the Azure classic portal (or respective Azure AD PowerShell cmdlet parameter). Additional URIs can be added via the application manifest; see Understanding the Azure AD Application Manifest for details. This collection is also used to populate the Web application's servicePrincipalNames collection.

Notes: not nullable, the any operator is required for filter expressions on multi-valued properties; for more information, see Supported Queries, Filters, and Paging Options.
keyCredentialsCollection(KeyCredential)POST, GET, PATCHThe collection of key credentials associated with the application

Notes: not nullable
knownClientApplicationsCollection(Edm.Guid)POST, GET, PATCHClient applications that are tied to this resource application. Consent to any of the known client applications will result in implicit consent to the resource application through a combined consent dialog (showing the OAuth permission scopes required by the client and the resource).

Notes: Requires version 1.5, not nullable.
logoutUrlEdm.StringPOST, GET, PATCH
mainLogoEdm.StreamPOST, GET, PATCHThe main logo for the application.

Notes: not nullable
oauth2AllowImplicitFlowEdm.BooleanPOST, GET, PATCHSpecifies whether this web application can request OAuth2.0 implicit flow tokens. The default is false.

Notes: Requires version 1.5, not nullable.
oauth2AllowUrlPathMatchingEdm.BooleanPOST, GET, PATCHSpecifies whether, as part of OAuth 2.0 token requests, Azure AD will allow path matching of the redirect URI against the application's replyUrls. The default is false.

Notes: Requires version 1.5, not nullable.
oauth2PermissionsCollection(OAuth2Permission)POST, GET, PATCHThe collection of OAuth 2.0 permission scopes that the web API (resource) application exposes to client applications. These permission scopes may be granted to client applications during consent.

Notes: Requires version 1.5, not nullable.
oauth2RequiredPostResponseEdm.GuidPOST, GET, PATCHSpecifies whether, as part of OAuth 2.0 token requests, Azure AD will allow POST requests, as opposed to GET requests. The default is false, which specifies that only GET requests will be allowed.

Notes: Requires version 1.5, not nullable.
objectIdEdm.GuidGETThe unique identifier for the application. Inherited from DirectoryObject.

Notes: key, immutable, not nullable, unique
objectTypeEdm.StringGETA string that identifies the object type. For applications the value is always "Application". Inherited from DirectoryObject.
optionalClaimsOptionalClaimsPOST, GET, PATCHThe optional claims returned in the token by the security token service for this specific app.
passwordCredentialsCollection(PasswordCredential)POST, GET, PATCHThe collection of password credentials associated with the application.

Notes: not nullable
publicClientEdm.BooleanPOST, GETSpecifies whether this application is a public client (such as an installed application running on a mobile device). Default is false.
recordConsentConditionsEdm.StringGETDo not use. May be removed in future versions

Notes: Requires version 1.6.
replyUrlsCollection(Edm.String)POST, GET, PATCHSpecifies the URLs that user tokens are sent to for sign in, or the redirect URIs that OAuth 2.0 authorization codes and access tokens are sent to.

Notes: not nullable
requiredResourceAccessCollection(RequiredResourceAccess)POST, GET, PATCHSpecifies resources that this application requires access to and the set of OAuth permission scopes and application roles that it needs under each of those resources. This pre-configuration of required resource access drives the consent experience.

Notes: Requires version 1.5, not nullable.
samlMetadataUrlEdm.StringPOST, GET, PATCHThe URL to the SAML metadata for the application.

Navigation Properties

NameToMultiplicity
(From/To)
Description
extensionPropertiesExtensionProperty*/*The extension properties associated with the application. Requires 1.5 or newer.
ownersDirectoryObject*/*Directory objects that are owners of the application. The owners are a set of non-admin users who are allowed to modify this object. Requires version 2013-11-08 or newer. Inherited from DirectoryObject.
policiesPolicy*/*Policies assigned to the application.
serviceEndpointsServiceEndpoint1/*Service endpoints available for discovery. For more information, see the ServiceEndpoint topic. HTTP Methods: POST, GET, and DELETE. Requires version 1.6 or newer.

Note: Inherited navigation properties that are not listed are not supported. Requests addressed to unsupported navigation properties return 400 Bad Request.

Supported Operations

The following operations are supported on applications (HTTP methods are listed in parentheses):

  • Create (POST)
  • Read (GET)
  • Update (PATCH)
  • Delete (DELETE)

The following operations are supported on application navigation properties. Not all operations may be supported on every navigation property.

  • Read (GET)
  • Update (POST)
  • Delete (DELETE)

The following action may be called on applications.

  • restore to restore a deleted application. Requires version 1.5 or newer.

AppRoleAssignment Entity

Used to record when a user or group is assigned to an application. In this case, the role assignment will result in an application tile showing up on the user's app access panel. This entity may also be used to grant another application (modeled as a service principal) access to a resource application in a particular role. You can create, read, update, and delete role assignments. Inherits from DirectoryObject.

Important: Introduced in version 1.5.

Properties

Declared Properties

NameTypeSupportsDescription
creationTimestampEdm.DateTimeGETThe time when the grant was created.
deletionTimestampEdm.DateTimeGETThis property is not valid for app role assignment and always returns null. Inherited from DirectoryObject.

Notes: Requires version 1.5 or newer.
idEdm.GuidPOST (Required), GET, PATCHThe role id that was assigned to the principal. This role must be declared by the target resource application resourceId in its appRoles property. Where the resource does not declare any permissions, a default id (zero GUID) must be specified.

Notes: not nullable.
principalDisplayNameEdm.StringGETThe display name of the principal that was granted the access.
objectIdEdm.StringGETThe unique identifier for the application role assignment. Inherited from DirectoryObject.

Notes: key, immutable, not nullable, unique.
objectTypeEdm.StringGETA string that identifies the object type. For application role assignments the value is always "AppRoleAssignment". Inherited from DirectoryObject.
principalIdEdm.GuidPOST (Required), GET, PATCHThe unique identifier (objectId) for the principal being granted the access.

Notes: required.
principalTypeEdm.StringGETThe type of principal. This can either be "User", "Group" or "ServicePrincipal".
resourceDisplayNameEdm.StringGETThe display name of the resource to which the assignment was made.
resourceIdEdm.GuidPOST (Required), GET, PATCHThe unique identifier (objectId) for the target resource (service principal) for which the assignment was made.

Navigation Properties
None.

Note: Inherited navigation properties that are not listed are not supported. Requests addressed to unsupported navigation properties return 400 Bad Request.


Contact Entity

Represents an organizational contact. Inherits from DirectoryObject.

Organizational contacts represent users that are not in your company directory. They are mail-enabled entities and typically represent individuals who are external to your company or organization. Organizational contacts cannot be authenticated using Azure AD, nor can they be assigned licenses.

Organizational contacts can be created in your tenant through syncing with an on-premises directory using Azure AD Connect, or they can be created through one of the Exchange Online management portals or the Exchange Online PowerShell cmdlets. For more information about Azure AD Connect, see Integrating your on-premises identities with Azure Active Directory. For more information about Exchange Online management tools, see Exchange Online Setup and Administration.

You cannot create organizational contacts with the Graph API. You can, however, update and delete contacts that are not currently synced from an on-premises directory; that is, contacts for which the dirSyncEnabled property is null or false. You cannot update or delete contacts for which the dirSyncEnabled property is true.

Note: Organizational contacts are directory entities, which represent external users. They should not be confused with O365 Outlook Personal contacts.

Properties

Declared Properties

NameTypeSupportsDescription
cityEdm.StringGET ($filter), PATCHThe city in which the contact is located.
countryEdm.StringGET ($filter), PATCHThe country/region in which the contact is located.
deletionTimestampEdm.DateTimeGETThis property is not valid for contacts and always returns null. Inherited from DirectoryObject.

Notes: Requires version 1.5 or newer.
departmentEdm.StringGET ($filter), PATCHThe name for the department in which the contact works.
dirSyncEnabledEdm.BooleanGET ($filter)true if this object is synced from an on-premises directory; false if this object was originally synced from an on-premises directory but is no longer synced; null if this object has never been synced from an on-premises directory (default).
displayNameEdm.StringGET ($filter), PATCHThe display name for the contact.
facsimileTelephoneNumberEdm.StringGET, PATCHThe telephone number of the contact's business fax machine.
givenNameEdm.StringGET ($filter), PATCHThe given name (first name) of the contact.
jobTitleEdm.StringGET ($filter), PATCHThe contact's job title.
lastDirSyncTimeEdm.DateTimeGET ($filter)Indicates the last time at which the object was synced with the on-premises directory.
mailEdm.StringGET ($filter)The SMTP address for the contact, for example, "jeff@contoso.onmicrosoft.com".
mailNicknameEdm.StringGET ($filter), PATCHThe mail alias for the contact.
mobileEdm.StringGET, PATCHThe primary cellular telephone number for the contact.
objectIdEdm.StringGETThe unique identifier for the contact. Inherited from DirectoryObject.

Notes: key, immutable, not nullable, unique.
objectTypeEdm.StringGETA string that identifies the object type. For contacts the value is always "Contact". Inherited from DirectoryObject.
physicalDeliveryOfficeNameEdm.StringGET, PATCHThe office location in the contact's place of business.
postalCodeEdm.StringGET, PATCHThe postal code for the contact's postal address. The postal code is specific to the contact's country/region. In the United States of America, this attribute contains the ZIP code.
provisioningErrorsCollection(ProvisioningError)GET, PATCHA collection of error details that are preventing this contact from being provisioned successfully.

Note: not nullable
proxyAddressesCollection(Edm.String)GET ($filter)Note: unique, not nullable, the any operator is required for filter expressions on multi-valued properties; for more information, see Supported Queries, Filters, and Paging Options.
sipProxyAddressEdm.StringGETSpecifies the voice over IP (VOIP) session initiation protocol (SIP) address for the contact.

Notes: Requires version 1.5 or newer.
stateEdm.StringGET ($filter), PATCHThe state or province in the contact's address.
streetAddressEdm.StringGET, PATCHThe street address of the contact's place of business.
surnameEdm.StringGET ($filter), PATCHThe contact's surname (family name or last name).
telephoneNumberEdm.StringGET, PATCHThe primary telephone number of the contact's place of business.
thumbnailPhotoEdm.StreamGET, PATCHA thumbnail photo to be displayed for the contact.

Note: not nullable

Navigation Properties

NameToMultiplicity
(From/To)
Description
managerDirectoryObject

(Only User and Contact objects are supported.)
*/0..1The user or contact that is this contact's manager. Inherited from DirectoryObject.

HTTP Methods: GET, PUT, DELETE
directReportsDirectoryObject

(Only User and Contact objects are supported.)
*/*The contact's direct reports. (The users and contacts that have their manager property set to this contact.) Inherited from DirectoryObject.

HTTP Methods: GET
memberOfDirectoryObject

(Only Group objects are supported.)
*/*Groups that this contact is a member of. Inherited from DirectoryObject.

HTTP Methods: GET

Note: Inherited navigation properties that are not listed are not supported. Requests addressed to unsupported navigation properties return 400 Bad Request.

Supported Operations

The following operations are supported on contacts (the HTTP method used for each is in parentheses):

  • Read (GET)
  • Update (PATCH): only contacts that are not synced from an on-premises directory (dirSyncEnabled is null or false).
  • Delete (DELETE)

The following operations are supported on contact navigation properties; not all operations may be supported on every navigation property.

  • Read (GET)
  • Update (PUT): manager property, only on contacts that are not synced from an on-premises directory (dirSyncEnabled is null or false).
  • Delete (DELETE): manager property, only on contacts that are not synced from an on-premises directory (dirSyncEnabled is null or false).

The following actions and functions may be called on contacts:

  • checkMemberGroups to check a contact’s membership in a list of groups. The check is transitive.
  • getMemberGroups to return a list of the groups that a contact is a member of. The check is transitive.
  • isMemberOf to check whether a contact is a member of a specified group. The check is transitive.

Remarks

Contacts are mail-enabled entities and cannot be created by using the Graph API. They can be updated; however, update is only supported for contacts with the dirSyncEnabled property set null or false. Contacts can be deleted.


Contract Entity

Exists in Partner Tenants only. Partner Tenants are Azure AD tenants that belong to Microsoft Partners who are either part of Office 365 Syndication, Microsoft Cloud Solution Provider, or Microsoft Advisor partner programs. Represents an existing partnership that the Partner Tenant has with a Customer Tenant. Read-only. Inherits from DirectoryObject.

Important: Introduced in version 1.5.

Properties

Declared Properties

NameTypeSupportsDescription
contractTypeEdm.StringGETType of the contract. Possible values are:
  • "SyndicationPartner", which indicates a partner that exclusively resells and manages O365 and Intune for this customer. They resell and support their customers.
  • "BreadthPartner", which indicates that the partner has the ability to provide administrative support for this customer. However the partner is not allowed to resell to the customer.
  • "ResellerPartner", which indicates a partner that is similar to a syndication partner, except that it doesn’t have exclusive access to a tenant. In the syndication case the customer cannot buy additional direct subscriptions from Microsoft or from other partners.
customerContextIdEdm.GuidGET ($filter)The unique identifier for the customer tenant referenced by this partnership. Corresponds to the objectId property of the customer tenant's TenantDetail object.
defaultDomainNameEdm.StringGET ($filter)A copy of the customer tenant's default domain name. The copy is made when the partnership with the customer is established. It is not automatically updated if the customer tenant's default domain name changes.
deletionTimestampEdm.DateTimeGETThis property is not valid for contracts and always returns null. Inherited from DirectoryObject.

Notes: Requires version 1.5 or newer.
displayNameEdm.StringGET ($filter)A copy of the customer tenant's display name. The copy is made when the partnership with the customer is established. It is not automatically updated if the customer tenant's display name changes.
objectTypeEdm.StringGETA string that identifies the object type. The value is always “Contract”. Inherited from DirectoryObject.
objectIdEdm.StringGETThe unique identifier for the partnership. Inherited from DirectoryObject.

Notes: key, immutable, not nullable, unique.

Navigation Properties
None.

Note: Inherited navigation properties that are not listed are not supported. Requests addressed to unsupported navigation properties return 400 Bad Request.

Supported Operations

The following operations are supported on contracts (the HTTP method used for each is in parentheses):

  • Read (GET)

Device Entity

Represents a device registered in the directory. Inherits from DirectoryObject.

Properties

Declared Properties

NameTypeSupportsDescription
accountEnabledEdm.BooleanPOST (required), GET ($filter), PATCHtrue if the account is enabled; otherwise, false. Default is true.
alternativeSecurityIdsCollection(AlternativeSecurityId)POST (required), GET ($filter), PATCHNotes: For internal use only. Not nullable, the any operator is required for filter expressions on multi-valued properties; for more information, see Supported Queries, Filters, and Paging Options.
approximateLastLogonTimeStampEdm.DateTimePOST, GET, PATCHThe Timestamp type represents date and time information using ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 would look like this: '2014-01-01T00:00:00Z'. Read-only.
deletionTimestampEdm.DateTimeGETThis property is not valid for devices and always returns null. Inherited from DirectoryObject.

Notes: Requires version 1.5 or newer.
deviceIdEdm.GuidPOST (Required), GET ($filter), PATCHUnique identifier set by Azure Device Registration Service at the time of registration.
deviceObjectVersionEdm.Int32POST, GET, PATCHFor internal use only.
deviceOSTypeEdm.StringPOST (Required), GET, PATCHThe type of operating system on the device. Required.
deviceOSVersionEdm.StringPOST (Required), GET, PATCHThe version of the operating system on the device. Required.
devicePhysicalIdsCollection(Edm.String)POST, GET ($filter), PATCHNotes: For internal use. Not nullable.
dirSyncEnabledEdm.BooleanGET ($filter)true if this object is synced from an on-premises directory; false if this object was originally synced from an on-premises directory but is no longer synced; null if this object has never been synced from an on-premises directory (default).
displayNameEdm.StringPOST (Required), GET ($filter), PATCHThe display name for the device. Required.
isCompliantEdm.BooleanPOST, GET, PATCHtrue if the device complies with Mobile Device Management (MDM) policies; otherwise, false. This can only be updated by Intune for any device OS type or by an approved MDM app for Windows OS devices.
IsManagedEdm.BooleanPOST, GET, PATCHtrue if the device is managed by a Mobile Device Management (MDM) app such as Intune; otherwise, false. This can only be updated by Intune for any device OS type or by an approved MDM app for Windows OS devices.
lastDirSyncTimeEdm.DateTimeGET ($filter)The last time at which the object was synced with the on-premises directory. The Timestamp type represents date and time information using ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 would look like this: '2014-01-01T00:00:00Z'. Read-only.
objectIdEdm.StringGETThe unique identifier for the device. Inherited from DirectoryObject.

Notes: key, immutable, not nullable, unique, read-only
objectTypeEdm.StringGETA string that identifies the object type. For devices the value is always "Device". Inherited from DirectoryObject

Navigation Properties

NameToMultiplicity
(From/To)
Description
registeredOwnersUser*/*Users that are registered owners of the device.
registeredUsersUser*/*Users that are registered users of the device.

Note: Inherited navigation properties that are not listed are not supported. Requests addressed to unsupported navigation properties return 400 Bad Request.

Supported Operations

The following operations are supported on devices (HTTP methods are listed in parentheses):

  • Create (CREATE)
  • Read (GET)
  • Update (PATCH)
  • Delete (DELETE)

The following operations are supported on device navigation properties. Not all operations may be supported on every navigation property.

  • Read (GET)
  • Update (PUT)
  • Delete (DELETE)

No functions or actions are supported on devices.


DirectoryLinkChange Entity

A DirectoryLinkChange object is returned in the result set of a differential query to indicate that a property of a contact, a user, or a group that is represented by a link has changed since the last differential query. The DirectoryLinkChange object will represent a change to a user’s or contact’s manager property or a change to a group’s members property. For more information about differential queries, see Differential Query. Inherits from DirectoryObject.

Properties

Declared Properties

NameTypeSupportsDescription
associationTypeEdm.StringGETA string that identifies the association type to which the change applies. The value is either "Member" or "Manager".
deletionTimestampEdm.DateTimeGETThis property is not valid for directory link change objects and always returns null. Inherited from DirectoryObject.

Notes: Requires version 1.5 or newer.
objectIdEdm.StringGETThe unique identifier for the directory link change object. For DirectoryLinkChange objects, the value is always 00000000-0000-0000-0000-000000000000. Inherited from DirectoryObject.

Note: key immutable, not nullable, unique
objectTypeEdm.StringGETA string that identifies the object type. For DirectoryLinkChange objects, the value is always "DirectoryLinkChange". DirectoryObject
sourceObjectIdEdm.StringGETThe object ID for the source object; for example, "7373b0af-d462-406e-ad26-f2bc96d823d8".
sourceObjectTypeEdm.StringGETA string that identifies the source object type; this will be one of the following: "Group", "User", or "Contact".
sourceObjectUriEdm.StringGETThe URI for the source object; for example, "https://graph.windows.net/contoso.com/groups/7373b0af-d462-406e-ad26-f2bc96d823d8".
targetObjectIdEdm.StringGETThe object ID for the target object; for example, "dca803ab-bf26-4753-bf20-e1c56a9c34e2".
targetObjectTypeEdm.StringGETA string that identifies the source object type; this will be one of the following: "Group", "User", or "Contact".
targetObjectUriEdm.StringGETThe URI for the target object; for example, "https://graph.windows.net/contoso.com/users/dca803ab-bf26-4753-bf20-e1c56a9c34e2".

Navigation Properties
None.

Note: Inherited navigation properties that are not listed are not supported. Requests addressed to unsupported navigation properties return 400 Bad Request.


DirectoryObject Entity

Represents an Azure Active Directory object. The DirectoryObject type is the base type for most of the other directory entity types.

Properties

Declared Properties

NameTypeSupportsDescription
deletionTimestampEdm.DateTimeGETThe time at which the directory object was deleted. It only applies to those directory objects which can be restored. Currently it is only supported for deleted Application objects; all other entities return null for this property.

Notes: Requires version 1.5 or newer.
objectIdEdm.StringGETA Guid that is the unique identifier for the object; for example, 12345678-9abc-def0-1234-56789abcde.

Notes: key, immutable, not nullable, unique.
objectTypeEdm.StringGETA string that identifies the object type. For example, for groups the value is always "Group".

Navigation Properties

NameToMultiplicity
(From/To)
Description
createdObjectsDirectoryObject*/*The directory objects that were created by the current object. Read only. Requires version 2013-11-08 or newer.
createdOnBehalfOfDirectoryObject*/0..1The directory object that that this object was created on behalf of. Read only. Requires version 2013-11-08 or newer.
managerDirectoryObject*/0..1This object's manager. Valid on users and contacts. Returns a user or a contact.
directReportsDirectoryObject*/*Users and contacts that report to this object. Valid on users and contacts. Returns users and contacts. Read only.
membersDirectoryObject*/*Objects that are members of this object. Valid on groups and roles. On groups, returns contacts, users, and groups. On roles, returns users and service principals.
memberOfDirectoryObject*/*Objects that this object is a member of. Valid on contacts, groups, service principals, and users. On contacts, returns groups. On groups, returns groups. On users, returns groups and roles. On service principals, returns roles. Read only.

The property is not transitive. For example, if User A is a member of Group B and Group B is a member of Group C, the memberOf property on User A will not return Group C.
ownedObjectsDirectoryObject*/*The directory objects that are owned by the current object. Read only. Requires version 2013-11-08 or newer.
ownersDirectoryObject*/*The directory objects that are owners of the current object. The owners are a set of non-admin users who are allowed to modify this object. Requires version 2013-11-08 or newer.

Note: Not all navigation properties are necessarily valid on the entity types that inherit from DirectoryObject. If a request for a property that is not valid for a specific entity is sent, a 400 Bad Request response is returned. For more information about which navigation properties are valid on specific entities, consult the documentation for that entity type.

Supported Operations

The full set of operations that are supported on directory objects are the following (the HTTP method used for each is in parentheses): Create (POST), Read (GET), Update (PATCH), and Delete (DELETE). However, not all of these operations are supported on every entity type. The declared properties of directory object are read-only; they cannot be specified in create or update operations.

The potential set of operations supported on each of the navigation properties are:

  • createdObjects: Read (GET).
  • createdOnBehalfOf: Read (GET).
  • manager: Read (GET), Update (PUT), and Delete (DELETE).
  • directReports: Read (GET).
  • members: Read (GET), Update (POST), and Delete (DELETE).
  • memberOf: Read (GET).
  • ownedObjects: Read (GET).
  • owners: Read (GET), Update (POST), and Delete (DELETE).

Not all navigation properties are necessarily supported on every entity type, nor are the set of potential operations for a navigation property necessarily supported on every entity type.

Whether a particular directory object supports a particular action or function, depends on the type of the directory object (the objectType property). For information about which object types support which functions or actions, see the documentation of the particular object, for example, user, group, etc., or of a particular function.

Consult the documentation for the specific entity type for information about operations supported for an entity.


DirectoryRole Entity

Represents an Azure AD directory role. Azure AD directory roles are also known as administrator roles. For more information about directory (administrator) roles, see Assigning administrator roles in Azure AD.

With the Graph API, you can assign users and service principals to directory roles to grant them the permissions of the target role. You can read directory role objects and update the members navigation property of directory roles, but you cannot delete directory roles or update their declared properties. Inherits from DirectoryObject.

To read a directory role or update its members, it must first be activated in the tenant. In versions prior to 1.5, all directory roles are activated by default. Beginning with version 1.5, only the Company Administrators directory role is activated by default. To activate other available directory roles you send a POST request with the objectId of the DirectoryRoleTemplate on which the directory role is based. See Supported Operations and Remarks for more information.

Important: Beginning with version 1.5, the Role entity type is renamed to DirectoryRole.

Properties

Declared Properties

NameTypeSupportsDescription
deletionTimestampEdm.DateTimeGETThis property is not valid for directory roles and always returns null. Inherited from DirectoryObject.

Notes: Requires version 1.5 or newer.
descriptionEdm.StringGETThe description for the directory role.
displayNameEdm.StringGETThe display name for the directory role.
isSystemEdm.BooleanGETtrue if the role is a system role; otherwise, false.
objectIdEdm.StringGETThe unique identifier for the directory role. Inherited from DirectoryObject.

Notes: key, immutable, not nullable, unique.
objectTypeEdm.StringGETA string that identifies the object type. For directory roles the value is always "DirectoryRole". Inherited from DirectoryObject.

Note: In versions prior to 1.5, the value will be "Role".
roleDisabledEdm.BooleanGETtrue if the directory role is disabled; otherwise, false.
roleTemplateIdStringPOST (Required), GETThe objectId of the DirectoryRoleTemplate that this role is based on.

Notes: In versions prior to version 1.5, the property is read only. In version 1.5 and later, the property must be specified when activating a directory role in a tenant with a POST operation. After the directory role has been activated, the property is read only.

Navigation Properties

NameToMultiplicity
(From/To)
Description
membersDirectoryObject

(User and ServicePrincipal are supported.)
*/*Users and service principals that are members of this directory role. Inherited from DirectoryObject.

HTTP Methods: GET, POST, DELETE

Note: Inherited navigation properties that are not listed are not supported. Requests addressed to unsupported navigation properties return 400 Bad Request.

Supported Operations

The following operations are supported on directory roles (the HTTP method used for each is in parentheses):

  • Create (POST): Supported in version 1.5 and later. Activates a directory role in the tenant using the DirectoryRoleTemplate specified by the roleTemplateId property in the request. After the directory role is activated, you can add and delete users and service principals from the role.
  • Read (GET)

The following operations are supported on directory role navigation properties:

  • Read (GET)
  • Update (POST)
  • Delete (DELETE)

No functions or actions may be called on directory roles; however, you can call getMemberObjects on a User or ServicePrincipal to determine its directory role memberships. Note that for users, this function also returns its direct and transitive group memberships.

Remarks

  • In version 1.5 and later, only the Company Adminstrators role is activated (and visible) in a tenant by default. Use the Create (POST) operation to activate additional directory roles. The operation specifies the roleTemplateId property in the request. This property contains the objectId of the DirectoryRoleTemplate instance that corresponds to the role you want to activate. After the directory role is activated you can add and delete users and service principals from it with the Graph API. In versions prior to 1.5, all directory roles (represented by the Role entity) are activated by default and the Create (POST) operation is not supported.
  • Directory roles cannot be deleted using the Graph API. Updates are supported on the members navigation property only. Both add and remove are supported on this property.
  • Query filter expressions are not supported on directory roles.

DirectoryRoleTemplate Entity

Represents a directory role template. A directory role template specifies the property values of a directory role (DirectoryRole). There is an associated directory role template object for each of the directory roles that may be activated in a tenant. Inherits from DirectoryObject.

To read a directory role or update its members, it must first be activated in the tenant. In versions prior to 1.5, all directory roles are activated by default. Beginning with version 1.5, only the Company Administrators directory role is activated by default. To activate other available directory roles you send a POST request to the /directoryRoles endpoint with the objectId of the directory role template on which the directory role is based specified in the roleTemplateId parameter of the request. For more information, see DirectoryRole.

Note: A directory role template is exposed for the Users directory role. The Users directory role is implicit and is not visible to directory clients. Every User in the tenant is assigned to this role by the infrastructure. The role is already activated. Do not use this template.

Important: Introduced in version 1.5.

Properties

Declared Properties

NameTypeSupportsDescription
descriptionEdm.StringGETThe description to set for the directory role.
deletionTimestampEdm.DateTimeGETThis property is not valid for directory role templates and always returns null. Inherited from DirectoryObject.

Notes: Requires version 1.5 or newer.
displayNameEdm.StringGETThe display name to set for the directory role.
objectIdEdm.StringGETThe unique identifier for the template. Inherited from DirectoryObject. In version 1.5 and later, you specify the objectId of the directory role template for the roleTemplateId property in the POST request activate a DirectoryRole in a tenant.

Notes: key, immutable, not nullable, unique.
objectTypeEdm.StringGETA string that identifies the object type. For role templates the value is always "RoleTemplate". Inherited from DirectoryObject.

Navigation Properties
None.

Note: Inherited navigation properties that are not listed are not supported. Requests addressed to unsupported navigation properties return 400 Bad Request.

Supported Operations

The following operations are supported on directory role templates (HTTP methods are listed in parentheses):

  • read (GET)

Domain Entity

Represents a domain associated with the tenant.

Important: Only available in version beta.

Properties

Declared Properties

NameTypeSupportsDescription
authenticationTypeEdm.StringGETIndicates what authentication type the domain is configured for. The value is either "Managed" or "Federated".
availabilityStatusEdm.StringGETThis property is always null except when the verify action is used. When the verify action is used, a Domain entity is returned in the response. The availabilityStatus property of the Domain entity in the response is either "AvailableImmediately" or "EmailVerifiedDomainTakeoverScheduled".
isAdminManagedEdm.BooleanGETfalse, if the DNS record management of the domain has been delegated to Office 365. Otherwise, true.

Notes: not nullable
isDefaultEdm.BooleanGET, PATCHIndicates whether or not this is the default domain that is used for user creation. There is only one default domain per company.

Notes: not nullable
isInitialEdm.BooleanGETIndicates whether or not this is the initial domain created by Microsoft Online Services (companyname.onmicrosoft.com). There is only one initial domain per company.

Notes: not nullable
isRootEdm.BooleanGETFor subdomains, this represents the root domain. Only root domains need to be verified, and all subdomains will be automatically verified.

Notes: not nullable
isVerifiedEdm.BooleanGETIndicates whether this domain has completed domain ownership verification or not.

Notes: not nullable
nameEdm.StringPOST (Required), GET ($filter)The fully qualified name of the domain.

Notes: key, immutable, not nullable, unique
supportedServicesCollection(Edm.String)GET, PATCHThe capabilities assigned to the domain. Can include 0, 1 or more of following values:
  • "Email"
  • "Sharepoint"
  • "EmailInternalRelayOnly"
  • "OfficeCommunicationsOnline"
  • "SharePointDefaultDomain"
  • "FullRedelegation"
  • "SharePointPublic"
  • "OrgIdAuthentication"
  • "Yammer"
  • "Intune"


Most of these values are read-only. The values which you can add/remove using Graph API includes:
  • "Email"
  • "OfficeCommunicationsOnline"
  • "Yammer"


Notes: not nullable

Navigation Properties

NameToMultiplicity
(From/To)
Description
serviceConfigurationRecordsDomainDnsRecord*/*DNS records that the customer has to add to the DNS zone file of the domain before the domain can be used by Microsoft Online services.
verificationDnsRecordsDomainDnsRecord*/*DNS records that the customer has to add to the DNS zone file of the domain before the customer can complete domain ownership verification with Azure AD.

DomainDnsRecord Entity

For each domain in the tenant, you may be required to add DNS record(s) to the DNS zone file of the domain before the domain can be used by Microsoft Online Services. The DomainDnsRecord entity is used to present such DNS records. Base entity for DomainDnsCnameRecord, DomainDnsMxRecord, DomainDnsSrvRecord and DomainDnsSrvRecord entities.

Important: Only available in version beta.

Properties

Declared Properties

NameTypeSupportsDescription
dnsRecordIdEdm.GuidGETUnique identifier assigned to this entity.

Notes: not nullable
isOptionalEdm.BooleanGETIndicates whether this record must be configured by the customer at the DNS host for Microsoft Online Services to operate correctly with the domain.

Notes: not nullable
labelEdm.StringGETIndicates the value to use when configuring the name of the DNS record at the DNS host.
recordTypeEdm.StringGETIndicates what type of DNS record this entity represents. The value can be one of the following:
  • "CName"
  • "Mx"
  • "Srv"
  • "Txt"


Notes: key
supportedServiceEdm.StringGETIndicates which Microsoft Online Service or feature has a dependency on this DNS record. Can be one of the following values:
  • null
  • "Email"
  • "Sharepoint"
  • "EmailInternalRelayOnly"
  • "OfficeCommunicationsOnline"
  • "SharePointDefaultDomain"
  • "FullRedelegation"
  • "SharePointPublic"
  • "OrgIdAuthentication"
  • "Yammer"
  • "Intune"
ttlEdm.Int32GETIndicates the value to use when configuring the time-to-live (ttl) property of the DNS record at the DNS host.

Notes: not nullable

DomainDnsCnameRecord Entity

Represents a CNAME record which needs to be added to the DNS zone file of a particular domain in the tenant. Inherited from DomainDnsRecord entity.

Important: Only available in version beta.

Properties

Declared Properties

NameTypeSupportsDescription
canonicalNameEdm.StringGETIndicates the value to use when configuring the canonical name of the CNAME record at the DNS host.
dnsRecordIdEdm.GuidGETUnique identifier assigned to this entity.

Notes: not nullable
isOptionalEdm.BooleanGETIndicates whether this CNAME record must be configured by the customer at the DNS host for Microsoft Online Services to operate correctly with the domain.

Notes: not nullable
labelEdm.StringGETIndicates the value to use when configuring the name of the CNAME record at the DNS host.
recordTypeEdm.StringGETIndicates what type of DNS record this entity represents. The value is always "CName".

Notes: key
supportedServiceEdm.StringGETIndicates which Microsoft Online Service or feature has a dependency on this CNAME record. Can be one of the following values:
  • null
  • "Email"
  • "Sharepoint"
  • "EmailInternalRelayOnly"
  • "OfficeCommunicationsOnline"
  • "SharePointDefaultDomain"
  • "FullRedelegation"
  • "SharePointPublic"
  • "OrgIdAuthentication"
  • "Yammer"
  • "Intune"
ttlEdm.Int32GETIndicates the value to use when configuring the time-to-live (ttl) property of the CNAME record at the DNS host.

Notes: not nullable

DomainDnsMxRecord Entity

Represents an MX record which needs to be added to the DNS zone file of a particular domain in the tenant. Inherited from DomainDnsRecord entity.

Important: Only available in version beta.

Properties

Declared Properties

NameTypeSupportsDescription
dnsRecordIdEdm.GuidGETUnique identifier assigned to this entity.

Notes: not nullable
isOptionalEdm.BooleanGETIndicates whether this MX record must be configured by the customer at the DNS host for Microsoft Online Services to operate correctly with the domain.

Notes: not nullable
labelEdm.StringGETValue to use when configuring the Alias/Host/Name property of the MX record at the DNS host.
mailExchangeEdm.StringGETValue to use when configuring the Answer/Destination/Value of the MX record at the DNS host.
recordTypeEdm.StringGETIndicates what type of DNS record this entity represents. The value is always "Mx".

Notes: key
preferenceEdm.Int32GETValue to use when configuring the Preference/Priority property of the MX record at the DNS host.
supportedServiceEdm.StringGETIndicates which Microsoft Online Service or feature has a dependency on this CNAME record. Can be one of the following values:
  • null
  • "Email"
  • "Sharepoint"
  • "EmailInternalRelayOnly"
  • "OfficeCommunicationsOnline"
  • "SharePointDefaultDomain"
  • "FullRedelegation"
  • "SharePointPublic"
  • "OrgIdAuthentication"
  • "Yammer"
  • "Intune"
ttlEdm.Int32GETValue to use when configuring the time-to-live (ttl) property of the MX record at the DNS host.

Notes: not nullable

DomainDnsSrvRecord Entity

Represents an SRV record which needs to be added to the DNS zone file of a particular domain in the tenant. Inherited from DomainDnsRecord entity.

Important: Only available in version beta.

Properties

Declared Properties

NameTypeSupportsDescription
dnsRecordIdEdm.GuidGETUnique identifier assigned to this entity.

Notes: not nullable
isOptionalEdm.BooleanGETIndicates whether this SRV record must be configured by the customer at the DNS host for Microsoft Online Services to operate correctly with the domain.

Notes: not nullable
labelEdm.StringGETValue to use when configuring the Name property of the SRV record at the DNS host.
nameTargetEdm.StringGETValue to use when configuring the Target property of the SRV record at the DNS host.
portEdm.Int32GETValue to use when configuring the Port property of the SRV record at the DNS host.
priorityEdm.Int32GETValue to use when configuring the Priority property of the SRV record at the DNS host.
protocolEdm.StringGETValue to use when configuring the Protocol property of the SRV record at the DNS host.
recordTypeEdm.StringGETIndicates what type of DNS record this entity represents. The value is always "Srv".

Notes: key
ServiceEdm.StringGETValue to use when configuring the Service property of the SRV record at the DNS host.
supportedServiceEdm.StringGETIndicates which Microsoft Online Service or feature has a dependency on this SRV record. Can be one of the following values:
  • null
  • "Email"
  • "Sharepoint"
  • "EmailInternalRelayOnly"
  • "OfficeCommunicationsOnline"
  • "SharePointDefaultDomain"
  • "FullRedelegation"
  • "SharePointPublic"
  • "OrgIdAuthentication"
  • "Yammer"
  • "Intune"
ttlEdm.Int32GETValue to use when configuring the Time-To-Live property of the SRV record at the DNS host.

Notes: not nullable
weightEdm.Int32GETValue to use when configuring the Weight property of the SRV record at the DNS host.

DomainDnsTxtRecord Entity

Represents a TXT record which needs to be added to the DNS zone file of a particular domain in the tenant. Inherited from DomainDnsRecord entity.

Properties

Declared Properties

NameTypeSupportsDescription
dnsRecordIdEdm.GuidGETUnique identifier assigned to this entity.

Notes: not nullable
isOptionalEdm.BooleanGETIndicates whether this MX record must be configured by the customer at the DNS host for Microsoft Online Services to operate correctly with the domain.

Notes: not nullable
labelEdm.StringGETValue to use when configuring the Alias/Host/Name property of the MX record at the DNS host.
recordTypeEdm.StringGETIndicates what type of DNS record this entity represents. The value is always "Mx".

Notes: key
supportedServiceEdm.StringGETIndicates which Microsoft Online Service or feature has a dependency on this CNAME record. Can be one of the following values:
  • null
  • "Email"
  • "Sharepoint"
  • "EmailInternalRelayOnly"
  • "OfficeCommunicationsOnline"
  • "SharePointDefaultDomain"
  • "FullRedelegation"
  • "SharePointPublic"
  • "OrgIdAuthentication"
  • "Yammer"
  • "Intune"
textEdm.StringGET
ttlEdm.Int32GETValue (in seconds) to use when configuring the Time-To-Live property of the TXT record at the DNS host.

Notes: not nullable

DomainDnsUnavailableRecord Entity

Inherited from DomainDnsRecord entity. When you query for the navigation property serviceConfigurationRecords for a Domain entity, you may get back one or more DomainDnsCnameRecord, DomainDnsMxRecord, DomainDnsSrvRecord and/or DomainDnsTxtRecord entities. These entities indicate what DNS records you must add to the zone file of the domain, before the domain can be used by Microsoft Online Services. When it is not possible to generate such entities, a DomainDnsUnavailableRecord Entity is returned instead.

Properties

Declared Properties

NameTypeSupportsDescription
descriptionEdm.StringGETProvides the reason why the DomainDnsUnavailableRecord entity is returned.

ExtensionProperty Entity

Allows an application to define and use a set of additional properties that can be added to directory objects (users, groups, tenant details, devices, applications, and service principals) without the application requiring an external data store. For more information about extension properties, see Directory Schema Extensions. Inherits from DirectoryObject.

Important: ExtensionProperty is introduced in version 1.5.

Properties

Declared Properties

NameTypeSupportsDescription
appDisplayNameEdm.StringGET
dataTypeEdm.StringPOST, GET, PATCHSpecifies the type of the directory extension property being added. Supported types are: Integer, LargeInteger, DateTime (must be specified in ISO 8601 - DateTime is stored in UTC), Binary, Boolean, and String.
deletionTimestampEdm.DateTimeGETThis property is not valid for extension properties and always returns null. Inherited from DirectoryObject.
objectIdEdm.StringGETThe unique identifier for the extension property. Inherited from DirectoryObject.

Notes: key, immutable, not nullable, unique.
objectTypeEdm.StringGETA string that identifies the object type. For extension properties the value is always "ExtensionProperty". Inherited from DirectoryObject.
nameEdm.StringPOST, GET, PATCHSpecifies the display name for the directory extension property.

Notes: not nullable.
isSyncedFromOnPremisesEdm.BooleanGETIndicates whether the extension property is synced from the on premises directory.

Notes: not nullable.
targetObjectsCollection(Edm.String)POST, GET, PATCHThe directory objects to which the directory extension property is being added. Supported directory entities that can be extended are: "User", "Group", "TenantDetail", "Device", "Application" and "ServicePrincipal"

Notes: not nullable.

Navigation Properties
None.

Note: Inherited navigation properties that are not listed are not supported. Requests addressed to unsupported navigation properties return 400 Bad Request.


Group Entity

Represents an Azure Active Directory Group. Inherits from DirectoryObject.

Properties

Declared Properties

NameTypeSupportsDescription
deletionTimestampEdm.DateTimeGETThis property is not valid for groups and always returns null. Inherited from DirectoryObject.

Notes: Requires version 1.5 or newer.
descriptionEdm.StringPOST, GET, PATCHAn optional description for the group.
dirSyncEnabledEdm.BooleanGET ($filter)true if this object is synced from an on-premises directory; false if this object was originally synced from an on-premises directory but is no longer synced; null if this object has never been synced from an on-premises directory (default).
displayNameEdm.StringPOST (Required), GET ($filter), PATCHThe display name for the group. This property is required when a group is created and it cannot be cleared during updates.
lastDirSyncTimeEdm.DateTimeGET ($filter)Indicates the last time at which the object was synced with the on-premises directory.
mailEdm.StringGET ($filter)The SMTP address for the group, for example, "serviceadmins@contoso.onmicrosoft.com".
mailEnabledEdm.BooleanPOST (Required), GET, PATCHSpecifies whether the group is mail-enabled. If the securityEnabled property is also true, the group is a mail-enabled security group; otherwise, the group is a Microsoft Exchange distribution group. Only (pure) security groups can be created using Azure AD Graph. For this reason, the property must be set false when creating a group and it cannot be updated using Azure AD Graph.
mailNicknameEdm.StringPOST (Required), GET ($filter), PATCHThe mail alias for the group. This property must be specified when a group is created.
objectIdEdm.StringGETThe unique identifier for the group. Inherited from DirectoryObject.

Notes: key, immutable, not nullable, unique.
objectTypeEdm.StringGETA string that identifies the object type. For groups the value is always "Group". Inherited from DirectoryObject.
onPremisesSecurityIdentifierStringGETContains the on-premises security identifier (SID) for the group that was synchronized from on-premises to the cloud.

Notes: Requires version 1.5 or newer.
provisioningErrorsCollection(ProvisioningError)GETA collection of error details that are preventing this group from being provisioned successfully.

Notes: not nullable.
preferredLanguageStringPOST, GET, PATCHThe preferred language for an Office 365 group. Should follow ISO 639-1 Code; for example "en-US".
proxyAddressesCollection(Edm.String)GET ($filter)

Notes: not nullable, the any operator is required for filter expressions on multi-valued properties; for more information, see Supported Queries, Filters, and Paging Options.
securityEnabledEdm.BooleanPOST (Required), GET ($filter), PATCHSpecifies whether the group is a security group. If the mailEnabled property is also true, the group is a mail-enabled security group; otherwise it is a security group. Only (pure) security groups can be created using Azure AD Graph. For this reason, the property must be set true when creating a group.
themeStringPOST, GET, PATCHSpecifies an Office 365 group's color theme. Possible values are Teal, Purple, Green, Blue, Pink, Orange or Red.

Navigation Properties

NameToTo MultiplicityDescription
membersDirectoryObject

(Only Contact, Group, ServicePrincipal, and User objects are supported)
*/*Users, contacts, groups, and service principals that are members of this group. Inherited from DirectoryObject.

HTTP Methods: GET (supported for all groups), POST (supported for security groups and mail-enabled security groups), DELETE (supported only for security groups)
memberOfDirectoryObject

(Only Group objects are supported)
*/*Groups that this group is a member of. Inherited from DirectoryObject.

HTTP Methods: GET (supported for all groups)
ownersDirectoryObject*/*The owners of the group. The owners are a set of non-admin users who are allowed to modify this object. Requires version 2013-11-08 or newer. Inherited from DirectoryObject.

HTTP Methods: GET (supported for all groups), POST (supported for security groups and mail-enabled security groups), DELETE (supported only for security groups)
appRoleAssignmentsDirectoryObject*/*Contains the set of applications that a group is assigned to.

Notes: Requires version 1.5 or newer.
extensionPropertiesDirectoryObject*/*Contains the extension properties associated with the application.

Notes: Requires version 1.5 or newer.

Note: Inherited navigation properties that are not listed are not supported. Requests addressed to unsupported navigation properties return 400 Bad Request.

Supported Operations

The following operations are supported on users (the HTTP method used for each is in parentheses):

  • Create (POST): Supported only for security groups.
  • Read (GET): Supported for all groups.
  • Update (PATCH): Supported only for security groups and mail-enabled security groups. Not all properties can be updated.
  • Delete (DELETE): Supported only for security groups.

The following operations are supported on group navigation properties:

  • Read (GET): Supported for all groups.
  • Update (POST): Supported only for security groups and mail-enabled security groups. (members and owners only.)
  • Delete (DELETE): Supported only for security groups. (members and owners only.)

The following actions and functions may be called on groups:

  • checkMemberGroups to check a group’s membership in a list of groups. The check is transitive.
  • getAvailableExtensionProperties to return a list of the extension properties that have been registered for a group. Requires version 1.5 or newer.
  • getMemberGroups to return a list of the groups that a group is a member of. The check is transitive.
  • isMemberOf to check whether a group is a member of a specified group. The check is transitive.

Remarks

  • There are three kinds of groups: mail distribution groups (mailEnabled property true and securityEnabled property false); mail-enabled security groups (mailEnabled property true and securityEnabled property true); and, (pure) security groups (mailEnabled property false and securityEnabled property true).
  • You can only create security groups using the Graph API (you cannot create mail-enabled security groups or mail distribution groups). For this reason the mailEnabled property must be set false and the securityEnabled property must be set true when creating a group.
  • All properties marked required must be specified when creating a security group using the Graph API. These properties are: displayName, mailNickname, mailEnabled (false), securityEnabled (true).
  • You cannot update a group from a security group to a mail-enabled security group or to a mail distribution group using the Graph API.

LicenseDetail Entity

Contains information about a license assigned to a user.

The licenseDetails property of the User entity is of type LicenseDetail.

Important: Introduced in version 1.6.

Properties

Declared Properties

PropertyTypeSupportsDescription
objectIdEdm.StringGETThe unique identifier for the license detail object.

Notes: key, not nullable.
servicePlansCollection(ServicePlanInfo)GETInformation about the service plans assigned with the license.

Notes: not nullable.
skuIdEdm.GuidGETUnique identifier (GUID) for the service SKU. Equal to the skuId property on the related SubscribedSku object.
skuPartNumberEdm.StringGETUnique SKU display name. Equal to the skuPartNumber on the related SubscribedSku object; for example: "AAD_Premium".

Navigation Properties
None.

Note: Inherited navigation properties that are not listed are not supported. Requests addressed to unsupported navigation properties return 400 Bad Request.

Supported Operations

The following operations are supported on license detail (the HTTP method used for each is in parentheses):

  • Create (POST)
  • Read (GET)
  • Update (PATCH)
  • Delete (DELETE)

No functions or actions may be called on license detail.


OAuth2PermissionGrant Entity

Represents the OAuth 2.0 delegated permission scopes that have been granted to an application (represented by a service principal) as part of the user or admin consent process.

Important: Beginning with version 1.5, the Permission entity type is renamed to OAuth2PermissionGrant. In versions prior to 1.5, permissions created during consent were added to the permissions property of a user or service principal.

Properties

Declared Properties

PropertyTypeSupportsDescription
clientIdEdm.StringPOST, GETSpecifies the objectId of the service principal granted consent to impersonate the user when accessing the resource (represented by the resourceId).
consentTypeEdm.StringPOST, GETSpecifies whether consent was provided by the administrator on behalf of the organization or whether consent was provided by an individual. The possible values are "AllPrincipals" or "Principal".
expiryTimeEdm.DateTimePOST, GET, PATCHReserved. Returns null. Do not use.
objectIdEdm.StringGETThe unique identifier for the permission scope.

Notes: key, not nullable.
principalIdEdm.StringPOST, GETIf consentType is "AllPrincipals" this value is null, and the consent applies to all users in the organization. If consentType is "Principal" then this property specifies the objectId of the user that granted consent, and applies only for that user.
resourceIdEdm.StringPOST, GETSpecifies the objectId of the resource service principal to which access has been granted.
scopeEdm.StringPOST, GET, PATCHSpecifies the value of the scope claim that the resource application should expect in the OAuth 2.0 access token.
startTimeEdm.DateTimePOST, GETReserved. Returns null. Do not use.

Navigation Properties
None.

Note: Inherited navigation properties that are not listed are not supported. Requests addressed to unsupported navigation properties return 400 Bad Request.

Supported Operations

The following operations are supported on permission scopes (the HTTP method used for each is in parentheses):

  • Create (POST)
  • Read (GET)
  • Update (PATCH): scope property only.
  • Delete (DELETE)

No functions or actions may be called on permission scopes.

Remarks

  • In version 1.5 and newer, the oauth2PermissionGrants navigation property of the User entity and of the ServicePrincipal entity returns the OAuth2PermissionGrant objects associated with the user or service principal.
  • Prior to version 1.5, the permissions navigation property of the User entity and of the ServicePrincipal entity returns the Permission objects associated with the user or service principal.

Policy Entity

Represents an Azure AD policy. Policies are custom rules that can be enforced on applications, service principals, groups, or the entire organization they are assigned to. Currently only two types of policy are available:

  • Token Lifetime Policy - Specifies the lifetime duration of tokens issued for applications and service principals. This policy is described in further detail below.
  • Token Issuance Policy - Specifies characteristics of SAML tokens issued by Azure AD. This policy is described in further detail below.
PropertyTypeSupportsDescription
definitionEdm.StringPOST, GETThe string version of the specific policy. See the information regarding the format of this string in the sections below.
displayNameEdm.StringPOST, GET, PATCHA custom name for the policy.
IsOrganizationDefaultEdm.BooleanPOST, GET, PATCHIf set to true, activates this policy for the tenant. There can be many policies for the same policy type, but only one can be activated as the organization default. Optional, default value is false.
typeEdm.StringPOST, GETSpecifies the type of policy. Currently must be TokenLifetimePolicy or TokenIssuancePolicy.

Navigation Properties

NameToMultiplicity
(From/To)
Description
appliesToDirectoryObject*/*The applications, service principals, groups, or organization the policy applies to.

Supported Operations

The following operations are supported on permission scopes (the HTTP method used for each is in parentheses):

  • Create (POST)
  • Read (GET)
  • Update (PATCH)
  • Delete (DELETE)

Token Lifetime Policy

Specifies the lifetimes of tokens issued for various purposes. This kind of policy can be assigned to applications and service principals. There are four kinds of tokens whose lifetimes can be configured. Access/Refresh token pairs are obtained during authentication through a client, whereas ID/Session token pairs are obtained during authentication through a browser.

  • Access Token contains information about the identity and privileges associated with a user account that is used by clients to access protected resources like applications.
  • Refresh Token is obtained together with the access token when a user authenticates against Azure AD through a client to access a protected resource. While it is not revoked or left unused for more than the MaxInactiveTime (below), it can be used to obtain a new access/refresh token pair when the current access token expires.
  • ID Token behaves like an access token, but obtained through the browser.
  • Session Token behaves like a refresh token, but obtained through the browser.
Token Lifetime Policy Properties

The properties below form the JSON object that represents a token lifetime policy. This JSON object must be converted to a string with quotations escaped to be inserted into the "definition" common policy property. Examples are provided on this page.

Note: All time durations in these properties are specified in the format "dd.hh:mm:ss".

Note: Max values for properties denoted in "days" are 1 second short of the denoted number of days. For example, the max value of 1 days is specified as "23:59:59".

PropertyTypeDescriptionMin ValueMax ValueDefault Value
AccessTokenLifetimeStringControls how long both access and ID tokens are considered valid.10 minutes1 day1 hour
MaxInactiveTimeStringControls how old a refresh token can be before a client can no longer use it to retrieve a new access/refresh token pair to access a resource.10 minutes90 days14 days
MaxAgeSingleFactorStringControls how long a user can continue to use refresh tokens to get new access/refresh token pairs after the last time they authenticated successfully with only a single factor. Because single-factor is considered less secure than multi-factor authentication, it is recommended that this policy is set to an equal or lesser value than the MultiFactorRefreshTokenMaxAge.10 minutesuntil-revoked365 days or until-revoked
MaxAgeMultiFactorStringControls how long a user can continue to use refresh tokens to get new access/refresh token pairs after the last time they authenticated successfully with multi factors.10 minutesuntil-revoked365 days or until-revoked
MaxAgeSessionSingleFactorStringControls how long a user can continue to use session tokens to get new ID/session tokens after the last time they authenticated successfully with only a single factor. Because single-factor is considered less secure than multi-factor authentication, it is recommended that this policy is set to an equal or lesser value than the MultiFactorSessionTokenMaxAge10 minutesuntil-revoked365 or until-revoked
MaxAgeSessionMultiFactorStringControls how long a user can continue to use session tokens to get new ID/session tokens after the last time they authenticated successfully with multi factors.10 minutesuntil-revoked365 or until-revoked
VersionIntegerSet value of 1. Required.NoneNoneNone

Token Issuance Policy

Token issuance policies can be used to specify certain properties of SAML tokens issued by Azure AD during the Ws-Federation authentication protocol. This kind of policy can be assigned to applications and service principals. Currently, token issuance policies can modify three properties of SAML tokens:

  • The algorithm used to sign the SAML token. SHA-256 is used by default, but can be changed to use SHA-1.
  • Whether the SAML token is signed, the entire SAML response is signed, or both. By default, only the SAML token is signed.
  • The version of the SAML token issued. SAML 2.0 tokens are issued by default, but can be changd to use SAML 1.1.
Token Issuance Policy Properties

The properties below form the JSON object that represents a token issuance policy. This JSON object must be converted to a string with quotations escaped to be inserted into the "definition" common policy property. Examples are provided on this page.

PropertyTypeDescriptionValuesDefault Value
SamlTokenVersionStringControls the version of the SAML token issued.1.1
2.0
2.0
SigningAlgorithmStringControls the algorithm used for signing the SAML token and/or response.http://www.w3.org/2001/04/xmldsig-more#rsa-sha256
http://www.w3.org/2000/09/xmldsig#rsa-sha1
http://www.w3.org/2001/04/xmldsig-more#rsa-sha256
TokenResponseSigningPolicyStringControls whether the SAML token is signed, the SAML response is signed, or both. If the SAML token version is set to 1.1, then TokenOnly is the only allowed value.TokenOnly
ResponseOnly
ResponseAndToken
TokenOnly
VersionIntegerThe version of the token issuance policy. Required.1None

ServiceEndpoint Entity

The service endpoint entity contains service discovery information. Inherits from DirectoryObject.

The serviceEndpoints property of the Application and ServicePrincipal entities is of type ServiceEndpoint. Other services can use the information stored in the ServiceEndpoint entity to find this service and its addressable endpoints.

Important: Introduced in version 1.6.

Properties

Declared Properties

PropertyTypeSupportsDescription
capabilityEdm.StringPOST (Required), GETA text identifier for the service's capability. Examples are "Documents" and "Mail".
deletionTimestampEdm.DateTimeGETThis property is not valid for service endpoints and always returns null. Inherited from DirectoryObject.
objectIdEdm.StringGETThe unique identifier for the service endpoint. Inherited from DirectoryObject.

Notes: key, immutable, not nullable, unique.
objectTypeEdm.StringGETA string that identifies the object type. For service endpoints the value is always "ServiceEndpoint". Inherited from DirectoryObject.
serviceIdEdm.StringPOST, GETThe identifier of the service
serviceNameEdm.StringPOST, GETThe display name of the service.
UriEdm.StringPOST (Required), GETUri of the service’s endpoint.
resourceIdEdm.StringPOST, GETAn identifier for a specific resource within the service.

Navigation Properties
None.

Note: Inherited navigation properties that are not listed are not supported. Requests addressed to unsupported navigation properties return 400 Bad Request.

Supported Operations

No direct operations may be performed on service endpoints. They are only addressable through the serviceEndpoints property on an Application or a ServicePrincipal. The following operations are supported (the HTTP method used for each is in parentheses):

  • Create (POST) -- only on the serviceEndpoints navigation property of an Application.
  • Read (GET) -- on the serviceEndpoints navigation property of an Application or ServicePrincipal.
  • Delete (DELETE) -- only on the serviceEndpoints property of an Application.

No functions or actions may be called on service endpoints.

Remarks

  • The capability and uri properties are required when you add a service endpoint to an Application.

ServicePrincipal Entity

Represents an instance of an application in a directory. Inherits from DirectoryObject.

Properties

Declared Properties

NameTypeSupportsDescription
accountEnabledEdm.BooleanPOST, GET ($filter), PATCHtrue if the service principal account is enabled; otherwise, false.
addInsCollection(AddIn)GETDefines custom behavior that a consuming service can use to call an app in specific contexts. For example, applications which can render file streams may set the addIns property for its "FileHandler" functionality. This will let services like Office 365 call the application in the context of a document the user is working on.

Notes: Requires version 1.6.
appDisplayNameEdm.StringGETThe display name exposed by the associated application.
appIdEdm.GuidPOST (Required), GET ($filter), PATCHThe unique identifier for the associated application (its appId property).
appOwnerTenantIdEdm.GuidGET
appRoleAssignmentRequiredEdm.BooleanPOST, GET, PATCHSpecifies whether an AppRoleAssignment to a user or group is required before Azure AD will issue a user or access token to the application.

Notes: Requires version 1.5 or newer, not nullable.
appRolesCollection(AppRole)GETThe application roles exposed by the associated application. For more information see the appRoles property definition on the Application entity

Notes: Requires version 1.5 or newer, not nullable.
authenticationPolicyServicePrincipalAuthenticationPolicyGETReserved for internal use only. Do not use. Removed in version 1.5.

Notes: Available in version 2013-11-08 only.
deletionTimestampEdm.DateTimeGETThis property is not valid for service principals and always returns null. Inherited from DirectoryObject.

Notes: Requires version 1.5 or newer.
displayNameEdm.StringPOST, GET ($filter), PATCHThe display name for the service principal.
errorUrlEdm.StringPOST, GET, PATCH
homepageEdm.StringPOST, GET, PATCHThe URL to the homepage of the associated application.
keyCredentialsCollection(KeyCredential)POST, GET, PATCHThe collection of key credentials associated with the service principal.

Notes: not nullable.
logoutUrlEdm.StringPOST, GET, PATCH
oauth2PermissionsCollection(OAuth2Permission)GETThe OAuth 2.0 permissions exposed by the associated application. For more information see the oauth2Permissions property definition on the Application entity.

Notes: Requires version 1.5 or newer, not nullable.
objectIdEdm.StringGETThe unique identifier for the service principal. Inherited from DirectoryObject.

Notes: key, immutable, not nullable, unique.
objectTypeEdm.StringGETA string that identifies the object type. For service principals the value is always "ServicePrincipal". Inherited from DirectoryObject.
passwordCredentialsCollection(PasswordCredential)POST, GET, PATCHThe collection of password credentials associated with the service principal.

Notes: not nullable.
preferredTokenSigningKeyThumbprintEdm.StringGETReserved for internal use only. Do not write or otherwise rely on this property. May be removed in future versions.

Notes: Requires version 1.5 or newer.
publisherNameEdm.StringPOST, GET ($filter), PATCHThe display name of the tenant in which the associated application is specified.
replyUrlsCollection(Edm.String)POST, GET, PATCHThe URLs that user tokens are sent to for sign in with the associated application, or the redirect URIs that OAuth 2.0 authorization codes and access tokens are sent to for the associated application.

Notes: not nullable.
samlMetadataUrlEdm.StringPOST, GET, PATCH
servicePrincipalNamesCollection(Edm.String)POST, GET ($filter), PATCHBased on the identifierURIs collection, plus the application's appId property, these URIs are used to reference an application's service principal. A client will use these to:

• populate requiredResourceAccess, via "Permissions to other applications” in the Azure classic portal.
• specify a resource URI to acquire an access token, which is the URI returned in the “aud” claim.

See identifierURIs in the Application entity for details on how to update.

Notes: not nullable, the any operator is required for filter expressions on multi-valued properties; for more information, see Supported Queries, Filters, and Paging Options.
tagsCollection(Edm.String)POST, GET ($filter), PATCH

Notes: not nullable.

Navigation Properties

NameToMultiplicity
(From/To)
Description
appRoleAssignedToAppRoleAssignment*/*Principals (users, groups, and service principals) that are assigned to this service principal. Requires version 1.5 or newer.
appRoleAssignmentsAppRoleAssignment*/*Applications that the service principal is assigned to. Requires version 1.5 or newer.
createdObjectsDirectoryObject*/*Directory objects created by this service principal. Inherited from DirectoryObject. Requires version 2013-11-08 or newer.
memberOfDirectoryObject

(Only DirectoryRole and Group objects are supported)
*/*Roles and groups that this service principal is a direct member of. Inherited from DirectoryObject.

HTTP Methods: GET
oauth2PermissionGrantsOAuth2PermissionGrant*/*User impersonation grants associated with this service principal. Requires version 1.5 or newer.
ownedObjectsDirectoryObject*/*Directory objects that are owned by this service principal. Inherited from DirectoryObject. Requires version 2013-11-08 or newer.
ownersDirectoryObject*/*Directory objects that are owners of this service principal. The owners are a set of non-admin users who are allowed to modify this object. Inherited from DirectoryObject. Requires version 2013-11-08 or newer.
permissionsPermission*/*Renamed to oauth2PermissionGrants in version 1.5 and newer. In previous versions pointed to the permissions associated with the service principal. For information about the Permission entity type, see OAuth2PermissionGrant.
policiesPolicy*/*Policies assigned to the service principal.
serviceEndpointsServiceEndpoint1/*Service endpoints available for discovery. For more information, see the ServiceEndpoint topic. HTTP Methods: GET. Requires version 1.6 or newer.

Note: Inherited navigation properties that are not listed are not supported. Requests addressed to unsupported navigation properties return 400 Bad Request.

Supported Operations

The following operations are supported on service principals (the HTTP method used for each is in parentheses):

  • Create (POST)
  • Read (GET)
  • Update (PATCH)
  • Delete (DELETE)

The following operation is supported on navigation properties:

  • Read (GET)

The following actions and functions may be called on groups:

  • checkMemberGroups to check a service principal’s membership in a list of groups. The check is transitive.
  • getMemberGroups to return a list of the groups that a service principal is a member of. The check is transitive.
  • getMemberObjects to return a list of the groups and directory roles that a service principal is a member of. The check is transitive.

A principal must be in the Company Administrator role to perform operations on service principals.

Remarks

You must set the appId property to the ID of an application in the directory when you create a service principal.


SubscribedSku Entity

Contains information about a service SKU that a company is subscribed to.

Only the read operation is supported on subscribed SKUs; create, update, and delete are not supported. Query filter expressions are not supported.

Properties

Declared Properties

PropertyTypeSupportsDescription
appliesToEdm.StringGETFor example, "User" or "Company".

Notes: Requires version 1.6.
capabilityStatusEdm.StringGETFor example, "Enabled".
consumedUnitsEdm.Int32GETThe number of licenses that have been assigned.
objectIdEdm.StringGETThe unique identifier for the subscribed sku object.

Notes: key, not nullable.
prepaidUnitsLicenseUnitsDetailGETInformation about the number and status of prepaid licenses.
servicePlansCollection(ServicePlanInfo)GETInformation about the service plans that are available with the SKU.

Notes: not nullable.
skuIdEdm.GuidGETThe unique identifier (GUID) for the service SKU.
skuPartNumberEdm.StringGETThe SKU part number; for example: "AAD_PREMIUM" or "RMSBASIC".

Navigation Properties
None.

Note: Inherited navigation properties that are not listed are not supported. Requests addressed to unsupported navigation properties return 400 Bad Request.

Supported Operations

The following operations are supported on subscribed SKUs (the HTTP method used for each is in parentheses):

  • Read (GET)

Subscribed SKUs do not expose any navigation properties.

No functions or actions may be called on subscribed SKUs.


TenantDetail Entity

Represents an Azure Active Directory tenant. Only the read and update operations are supported on tenants; create and delete are not supported. Inherits from DirectoryObject.

Properties

Declared Properties

NameTypeSupportsDescription
assignedPlansCollection(AssignedPlan)GETThe collection of service plans associated with the tenant.

Notes: not nullable.
cityEdm.StringGET
companyLastDirSyncTimeEdm.DateTimeGETThe time and date at which the tenant was last synced with the on-premise directory.
countryEdm.StringGET
countryLetterCodeEdm.StringGET
deletionTimestampEdm.DateTimeGETThis property is not valid for tenants and always returns null. Inherited from DirectoryObject.

Notes: Requires version 1.5 or newer.
dirSyncEnabledEdm.BooleanGETtrue if this object is synced from an on-premises directory; false if this object was originally synced from an on-premises directory but is no longer synced; null if this object has never been synced from an on-premises directory (default).
displayNameEdm.StringGETThe display name for the tenant.
marketingNotificationEmailsCollection(Edm.String)GET, PATCH

Notes: not nullable.
objectIdEdm.StringGETThe unique identifier for the tenant. Inherited from DirectoryObject.

Notes: key, immutable, not nullable, unique.
objectTypeEdm.StringGETA string that identifies the object type. For tenants the value is always "Company". Inherited from DirectoryObject.
postalCodeEdm.StringGET
preferredLanguageEdm.StringGET
provisionedPlansCollection(ProvisionedPlan)GET

Notes: not nullable.
provisioningErrorsCollection(ProvisioningError)GET

Notes: not nullable.
stateEdm.StringGET
streetEdm.StringGET
technicalNotificationMailsCollection(Edm.String)GET, PATCH

Notes: not nullable.
telephoneNumberEdm.StringGET
tenantTypeEdm.StringGET

Notes: removed in version 1.5 and newer.
verifiedDomainsCollection(VerifiedDomain)GETThe collection of domains associated with this tenant.

Notes: not nullable.

Navigation Properties

NameToTo MultiplicityDescription
trustedCAsForPasswordlessAuthTrustedCAsForPasswordlessAuth1/1The set of certificate authorities used to validate the trust chain while performing password-less authentication. For more information, see Remarks.

Notes: Requires version 1.6 or newer.

Note: Inherited navigation properties that are not listed are not supported. Requests addressed to unsupported navigation properties return 400 Bad Request.

Supported Operations

The following operations are supported on tenants (the HTTP method used for each is in parentheses):

  • Read (GET)
  • Update (PATCH); only the marketingNotificationMails and technicalNotificationMails properties can be updated using the Graph API.

The following operations are supported on tenant navigation properties:

  • Read (GET)
  • Update (POST)
  • Delete (DELETE)

No functions or actions may be called on tenants.

Remarks

  • You cannot create or delete tenants using the Graph API.
  • Only the marketingNotificationMails and technicalNotificationMails properties can be updated using the Graph API.
  • Trusted certificate authorities enable users in a federated tenant to sign in using certificate-based authentication. To enable this scenario, configure the public certificates of the certificate authorities trusted for sign-in by setting the trustedCAsForPasswordlessAuth navigation property.
  • Query filter expressions are not supported on tenants.

TrustedCAsForPasswordlessAuth Entity

Represents a set of certificate authorities to validate the trust chain while performing password-less authentication.

The trustedCAsForPasswordlessAuth navigation property of the TenantDetail entity is a collection of trustedCAsForPasswordlessAuth. Clients can use this property to configure the public certificates of the authorities trusted for sign-in in order to enable users in a federated tenant to sign in using certificate-based authentication.

Important: Introduced in version 1.6.

Properties

Declared Properties

NameTypeSupportsDescription
idEdm.StringGETUnique identifier.

Notes: key, not nullable.
certificateAuthoritiesCollection(CertificateAuthorityInformation)POST (Required), GET, PATCHCollection of certificate authority information.

Navigation Properties
None.

Supported Operations

The following operations are supported on trusted certificate authorities (the HTTP method used for each is in parentheses):

  • Create (POST); only the certificateAuthorities property can be specified.
  • Read (GET)
  • Update (PATCH); only the certificateAuthorities property

Trusted certificates do not expose any navigation properties.

No functions or actions may be called on trusted certificate authorities.


User Entity

Represents an Azure AD user account. Inherits from DirectoryObject.

Properties

Declared Properties

NameTypeSupportsDescription
accountEnabledEdm.BooleanPOST (Required), GET ($filter), PATCHtrue if the account is enabled; otherwise, false. This property is required when a user is created.
assignedLicensesCollection(AssignedLicense)POST, GET, PATCHThe licenses that are assigned to the user.

Notes: not nullable.
assignedPlansCollection(AssignedPlan)GETThe plans that are assigned to the user.

Notes: not nullable.
cityEdm.StringPOST, GET ($filter), PATCHThe city in which the user is located.
countryEdm.StringPOST, GET ($filter), PATCHThe country/region in which the user is located; for example, "US" or "UK".
creationTypeEdm.StringPOST (Required for local accounts), GET ($filter)Indicates whether the user account is a local account for an Azure Active Directory B2C tenant. Possible values are "LocalAccount" and null. When creating a local account, the property is required and you must set it to "LocalAccount". When creating a work or school account, do not specify the property or set it to null. For more information about Azure Active Directory B2C, see the Azure Active Directory B2C documentation.

Notes: Requires version 1.6 or newer.
deletionTimestampEdm.DateTimeGETThis property is not valid for users and always returns null. Inherited from DirectoryObject.

Notes: Requires version 1.5 or newer.
departmentEdm.StringPOST, GET ($filter), PATCHThe name for the department in which the user works.
dirSyncEnabledEdm.BooleanGET ($filter)true if this object is synced from an on-premises directory; false if this object was originally synced from an on-premises directory but is no longer synced; null if this object has never been synced from an on-premises directory (default).
displayNameEdm.StringPOST (Required), GET ($filter), PATCH (but cannot be cleared)The name displayed in the address book for the user. This is usually the combination of the user's first name, middle initial and last name. This property is required when a user is created and it cannot be cleared during updates.
employeeIdEdm.StringPOST, GET ($filter), PATCHThe employee identifier assigned to the user by the organization.
facsimileTelephoneNumberEdm.StringPOST, GET, PATCHThe telephone number of the user's business fax machine.
givenNameEdm.StringPOST, GET ($filter), PATCHThe given name (first name) of the user.
immutableIdEdm.StringPOST (Required if using a federated domain for the UPN), GET ($filter), PATCHThis property is used to associate an on-premises Active Directory user account to their Azure AD user object. This property must be specified when creating a new user account in the Graph if you are using a federated domain for the user's userPrincipalName (UPN) property.

Important: The $ and _ characters cannot be used when specifying this property.

Notes: Requires version 2013-11-08 or newer.
jobTitleEdm.StringPOST, GET ($filter), PATCHThe user's job title.
lastDirSyncTimeEdm.DateTimeGET ($filter)Indicates the last time at which the object was synced with the on-premises directory; for example: "2013-02-16T03:04:54Z"
mailEdm.StringPOST, GET ($filter)The SMTP address for the user, for example, "jeff@contoso.onmicrosoft.com".
mailNicknameEdm.StringPOST (Required for work or school accounts), GET ($filter), PATCHThe mail alias for the user. This property is required when you create a work or school account; it is optional for a local account.
mobileEdm.StringPOST, GET, PATCHThe primary cellular telephone number for the user.
objectIdEdm.GuidGETThe unique identifier for the user. Inherited from DirectoryObject.

Notes: key, immutable, not nullable, unique.
objectTypeEdm.StringGETA string that identifies the object type. For users the value is always "User". Inherited from DirectoryObject.
onPremisesSecurityIdentifierEdm.StringGETContains the on-premises security identifier (SID) for the user that was synchronized from on-premises to the cloud.

Notes: Requires version 1.5 or newer.
otherMailsCollection(Edm.String)POST, GET ($filter), PATCHA list of additional email addresses for the user; for example: ["bob@contoso.com", "Robert@fabrikam.com"].

Notes: not nullable, the any operator is required for filter expressions on multi-valued properties; for more information, see Supported Queries, Filters, and Paging Options.
passwordPoliciesEdm.StringPOST, GET, PATCHSpecifies password policies for the user. This value is an enumeration with one possible value being "DisableStrongPassword", which allows weaker passwords than the default policy to be specified. "DisablePasswordExpiration" can also be specified. The two may be specified together; for example: "DisablePasswordExpiration, DisableStrongPassword".
passwordProfilePasswordProfilePOST (Required), PATCHSpecifies the password profile for the user. The profile contains the user's password. This property is required when a user is created.

The password in the profile must satisfy minimum requirements as specified by the passwordPolicies property. By default, a strong password is required. For information about the constraints that must be satisfied for a strong password, see Password policy under Change your password in the Microsoft Office 365 help pages. The passwordProfile is a write only property.
physicalDeliveryOfficeNameEdm.StringPOST, GET, PATCHThe office location in the user's place of business.
postalCodeEdm.StringPOST, GET, PATCHThe postal code for the user's postal address. The postal code is specific to the user's country/region. In the United States of America, this attribute contains the ZIP code.
preferredLanguageEdm.StringPOST, GET, PATCHThe preferred language for the user. Should follow ISO 639-1 Code; for example "en-US".
provisionedPlansCollection(ProvisionedPlan)GETThe plans that are provisioned for the user.

Notes: not nullable.
provisioningErrorsCollection(ProvisioningError)GETA collection of error details that are preventing this user from being provisioned successfully.
proxyAddressesCollection(Edm.String)GET ($filter)Fpr example: ["SMTP: bob@contoso.com", "smtp: bob@sales.contoso.com"]

Notes: unique, not nullable, the any operator is required for filter expressions on multi-valued properties; for more information, see Supported Queries, Filters, and Paging Options.
refreshTokensValidFromDateTimeEdm.DateTimePOST, GET, PATCHAny refresh tokens or sessions tokens (session cookies) issued before this time are invalid, and applications will get an error when using an invalid refresh or sessions token to acquire a delegated access token (to access APIs such as AD Graph). If this happens, the application will need to acquire a new refresh token by making a request to the authorize endpoint. Use Invalidate all refresh tokens to reset.
showInAddressListEdm.BooleanPOST, GET, PATCHtrue if the Outlook global address list should contain this user, otherwise false. If not set, this will be treated as true. For users invited through the invitation manager, this property will be set to false.
signInNamesCollection(SignInName)POST (Required for local accounts), GET ($filter)Specifies the collection of sign-in names for a local account in an Azure Active Directory B2C tenant. Each sign-in name must be unique in the tenant. The property must be specified when you create a local account user; do not specify it when you create a work or school account. For more information about Azure Active Directory B2C, see the Azure Active Directory B2C documentation.

Notes: Requires version 1.6 or newer.
sipProxyAddressEdm.StringGETSpecifies the voice over IP (VOIP) session initiation protocol (SIP) address for the user.

Notes: Requires version 1.5 or newer.
stateEdm.StringPOST, GET ($filter), PATCHThe state or province in the user's address.
streetAddressEdm.StringPOST, GET, PATCHThe street address of the user's place of business.
surnameEdm.StringPOST, GET ($filter), PATCHThe user's surname (family name or last name).

Notes: filterable, must be between 1 and 64 characters.
telephoneNumberEdm.StringPOST, GET, PATCHThe primary telephone number of the user's place of business.
thumbnailPhotoEdm.StreamPOST, GET, PATCHA thumbnail photo to be displayed for the user.

Notes: not nullable.
usageLocationEdm.StringPOST, GET ($filter), PATCHA two letter country code (ISO standard 3166). Required for users that will be assigned licenses due to legal requirement to check for availability of services in countries. Examples include: "US", "JP", and "GB".

Notes: not nullable.
userIdentitiesCollection(UserIdentity)POST (Required for social accounts), GET ($filter)Specifies the collection of userIdentities for a social user account in an Azure Active Directory B2C tenant. Each userIdentity (issuer and issuerIdentity as a pair) must be unique in the tenant. For more information about Azure Active Directory B2C, see the Azure Active Directory B2C documentation.

Notes: Requires version 1.6 or newer.
userPrincipalNameEdm.StringPOST (Required for work or school accounts), GET ($filter), PATCHThe user principal name (UPN) of the user. The UPN is an Internet-style login name for the user based on the Internet standard RFC 822. By convention, this should map to the user's email name. The general format is "alias@domain". For work or school accounts, the domain must be present in the tenant's collection of verified domains. This property is required when a work or school account is created; it is optional for local accounts.

The verified domains for the tenant can be accessed from the VerifiedDomains property of TenantDetail.

Notes: key, unique.
userTypeEdm.StringPOST, GET ($filter), PATCHA string value that can be used to classify user types in your directory, such as "Member" and "Guest".

Notes: Requires version 2013-11-08 or newer.

Navigation Properties

NameToMultiplicity
(From/To)
Description
managerDirectoryObject

(Only User and Contact objects are supported.)
*/0..1The user or contact that is this user's manager. Inherited from DirectoryObject.

HTTP Methods: GET, PUT, DELETE
directReportsDirectoryObject

(Only User and Contact objects are supported.)
*/*The users and contacts that report to the user. (The users and contacts that have their manager property set to this user.) Inherited from DirectoryObject.

HTTP Methods: GET
licenseDetailsLicenseDetail*/*

Notes: Requires version 1.6 or later.
memberOfDirectoryObject

(Only Group and DirectoryRole objects are supported.)
*/*The groups and directory roles that the user is a member of. Inherited from DirectoryObject.

HTTP Methods: GET
ownedDevicesDevice*/*Devices that are owned by the user.
permissionsPermission*/*The permissions associated with the user. The property is renamed to oauth2PermissionGrants and the Permission entity is renamed to OAuth2PermissionGrant in version 1.5 and newer. See the documentation for OAuth2PermssionGrant for documentation of the Permission entity type.

registeredDevicesDevice*/*Devices that are registered for the user.
createdObjectsDirectoryObject*/*Directory objects that were created by the user. Requires version 2013-11-08 or newer.
ownedObjectsDirectoryObject*/*Directory objects that are owned by the user. Requires version 2013-11-08 or newer.
appRoleAssignmentsAppRoleAssignment*/*The set of applications that this user is assigned to. Requires version 1.5 or newer.

HTTP Methods: GET, POST, DELETE
oauth2PermissionGrantsOAuth2PermissionGrant*/*The set of applications that are granted consent to impersonate this user. Requires version 1.5 or newer.

HTTP Methods: GET, POST, DELETE

Note: Inherited navigation properties that are not listed are not supported. Requests addressed to unsupported navigation properties return 400 Bad Request.

Supported Operations

The following operations are supported on users (the HTTP method used for each is in parentheses):

  • Create (POST)
  • Read (GET)
  • Update (PATCH)
  • Delete (DELETE)

The following operations are supported on user navigation properties; not all operations are supported on every navigation property.

  • Read (GET)
  • Update (PUT)
  • Delete (DELETE)

The following actions and functions may be called on users:

  • assignLicense to assign and/or remove a specified list of licenses from a user. Requires version 2013-11-08 or newer.
  • checkMemberGroups to check the user’s membership in a list of groups. The check is transitive.
  • getAvailableExtensionProperties to return a list of the extension properties that have been registered for a user. Requires version 1.5 or newer.
  • getMemberGroups to return a list of the groups that a user is a member of. The check is transitive.
  • getMemberObjects to return a list of the groups and directory roles that a user is a member of. The check is transitive.
  • isMemberOf to check whether a user is a member of a specified group. The check is transitive.

Remarks

  • To create a work or school account, the required properties are: accountEnabled, displayName, mailNickname, passwordProfile, and userPrincipalName. The password specified in the passwordProfile property must meet the tenant’s password complexity requirements. For more information, see the passwordPolicies property.
  • To create a local account, the required properties are: accountEnabled, creationType (must be set to “LocalAccount”), displayName, passwordProfile, and signInNames. The password specified in the passwordProfile property must meet the tenant’s password complexity requirements. For more information, see the passwordPolicies property.
  • In version 2013-11-08 and newer, the immutableId property must be specified when creating a new user account in the Graph if you are using a federated domain for the user’s userPrincipalName (UPN) property.
  • The displayName property cannot be cleared on updates.
  • The passwordProfile property always returns null. This is to prevent the user’s password from being displayed. You can reset the user’s password by updating the passwordProfile property.
  • In addition to the standard addressing available for all directory entities, users may be addressed by using the userPrincipalName property; for example, https://graph.windows.net/contoso.onmicrosoft.com/users/john@contoso.onmicrosoft.com?api-version=1.5.

Complex type reference

AddIn Type

Defines custom behavior that a consuming service can use to call an app in specific contexts. For example, applications which can render file streams may set the addIns property for its "FileHandler" functionality. This will let services like Office 365 call the application in context of the document the user is working on. The addins property of the Application and ServicePrincipal entities is a collection of AddIn.

Important: Introduced in version 1.6.

Properties

NameTypeRead/WriteDescription
idEdm.GuidRA unique identifier within the addins collection on a specific Application.
typeEdm.StringRWThe unique name for the functionality exposed by the app.
propertiesCollection(KeyValue)RW (Required on writes)The collection of key-value pairs that define parameters the consuming service can use or call. You must specify this property when performing a POST or a PATCH operation on the addIns collection.

AlternativeSecurityId Type

Contains an alternative security ID associated with a device. The alternativeSecurityIds property of the Device entity is a collection of AlternativeSecurityId.

Properties

NameTypeRead/WriteDescription
identityProviderEdm.String
keyEdm.Binary
typeEdm.Int32

AppRole Type

Represents an application role that may be requested by a client application calling another application or that may be used to assign an application to users or groups in a specified application role. The appRoles property of the ServicePrincipal entity and of the Application entity is a collection of AppRole.

Important: Requires version 1.5 or newer.

Properties

NameTypeRead/WriteDescription
allowedMemberTypesCollection(Edm.String)RWSpecifies whether this app role definition can be assigned to users and groups by setting to "User", or to other applications (that are accessing this application in daemon service scenarios) by setting to "Application", or to both.

Notes: not nullable.
descriptionEdm.StringRWPermission help text that appears in the admin app assignment and consent experiences.
displayNameEdm.StringRWDisplay name for the permission that appears in the admin consent and app assignment experiences.
idEdm.GuidRWUnique role identifier inside the appRoles collection.
isEnabledEdm.BooleanRWWhen creating or updating a role definition, this must be set to true (which is the default). To delete a role, this must first be set to false. At that point, in a subsequent call, this role may be removed.
valueEdm.StringRWSpecifies the value of the roles claim that the application should expect in the authentication and access tokens.

AssignedLicense Type

Represents a license assigned to a user. The assignedLicenses property of the User entity is a collection of AssignedLicense.

Properties

NameTypeRead/WriteDescription
disabledPlansCollection(Edm.Guid)RA collection of the unique identifiers for plans that have been disabled.

Notes: not nullable.
skuIdEdm.GuidRThe unique identifier for the service SKU. Same value as the skuId property of the related SubscribedSku object.

AssignedPlan Type

The assignedPlans property of both the User entity and the TenantDetail entity is a collection of AssignedPlan.

Properties

NameTypeRead/WriteDescription
assignedTimestampEdm.DateTimeRThe date and time at which the plan was assigned; for example: 2013-01-02T19:32:30Z.
capabilityStatusEdm.StringRFor example, "Enabled".
serviceEdm.StringRThe name of the service; for example, "SharePoint", "MicrosoftOffice", or "Exchange".
servicePlanIdEdm.GuidRA GUID that identifies the service plan.

CertificateAuthorityInformation Type

Represents a certificate authority used when validating the trust chain while performing password-less authentication. The certificateAuthorities property of the TrustedCAsForPasswordlessAuth entity is a collection of CertificateAuthorityInformation.

Important: Introduced in version 1.6.

Properties

NameTypeRead/WriteDescription
authorityTypeEdm.StringRW (Required on POST)Required. Must be set to one of two possible values: “RootAuthority” or “IntermediateAuthority”. It is used while validating certificates during authentication.
crlDistributionPointEdm.StringRWCertificate Revocation List (CRL) distribution points hold files which store the serial numbers of all certificates that have been revoked. This is typically a URI.
deltaCrlDistributionPointEdm.StringRWA URI that contains the list of all revoked certificates since the last time a full CRL was created.
trustedCertificateEdm.BinaryRW (Required on POST)Required. The public certificate in binary form.
trustedIssuerEdm.StringRRead only. Calculated from the trustedCertificate value.
trustedIssuerSkiEdm.StringRRead only. The subject key identifier is calculated from the trustedCertificate value.

KeyCredential Type

Contains a key credential associated with an application or a service principal. The keyCredentials property of the Application and ServicePrincipal entities is a collection of KeyCredential.

Properties

NameTypeRead/WriteDescription
customKeyIdentifierEdm.Binary
endDateEdm.DateTimeThe date and time at which the credential expires.
keyIdEdm.GuidThe unique identifier (GUID) for the key.
startDateEdm.DateTimeThe date and time at which the credential becomes valid.
typeEdm.StringThe type of key credential; for example, "Symmetric".
usageEdm.StringA string that describes the purpose for which the key can be used; for example, "Verify".
valueEdm.String

KeyValue Type

Contains a key-value pair that defines a parameter that a consuming service can use or call on an application specified in an AddIn. The properties property of the AddIn type is a collection of KeyValue.

Important: Introduced in version 1.6.

Properties

NameTypeRead/WriteDescription
keyEdm.StringRWThe key in the key value pair.
valueEdm.StringRWThe value of the key value pair.

LicenseUnitsDetail Type

Contains information and status about the prepaid units of a service SKU that a company is subscribed to.

The prepaidUnits property of the SubscribedSku entity is of type LicenseUnitsDetail.

Properties

NameTypeRead/WriteDescription
enabledEdm.Int32RThe number of units that are enabled.
suspendedEdm.Int32RThe number of units that are suspended.
warningEdm.Int32RThe number of units that are in warning status.

OAuth2Permission Type

Represents an OAuth 2.0 delegated permission scope. The specified OAuth 2.0 delegated permission scopes may be requested by client applications (through the requiredResourceAccess collection on the Application object) when calling a resource application. The oauth2Permissions property of the ServicePrincipal entity and of the Application entity is a collection of OAuth2Permission.

Important: Requires version 1.5 or newer.

Properties

NameTypeRead/WriteDescription
adminConsentDescriptionEdm.StringRWPermission help text that appears in the admin consent and app assignment experiences.
adminConsentDisplayNameEdm.StringRWDisplay name for the permission that appears in the admin consent and app assignment experiences.
idEdm. GuidRWUnique scope permission identifier inside the oauth2Permissions collection.
isEnabledEdm.BooleanRWWhen creating or updating a permission, this property must be set to true (which is the default). To delete a permission, this property must first be set to false. At that point, in a subsequent call, the permission may be removed.

Notes: not nullable.
typeEdm.StringRWSpecifies whether this scope permission can be consented to by an end user, or whether it is a tenant-wide permission that must be consented to by a Company Administrator. Possible values are "User" or "Admin".
userConsentDescriptionEdm.StringRWPermission help text that appears in the end user consent experience.
userConsentDisplayNameEdm.StringRWDisplay name for the permission that appears in the end user consent experience.
valueEdm.StringRWThe value of the scope claim that the resource application should expect in the OAuth 2.0 access token.

OptionalClaims Type

Contains optional claims associated with an application. An application can configure optional claims to be returned in each of three types of tokens (ID token, access token, SAML 2 token) it receives from the security token service. The application can configure a different set of optional claims to be returned in each token type. The OptionalClaims property of the Application entity is an OptionalClaims object.

Properties

NameTypeRead/WriteDescription
idTokenCollection (OptionalClaim)RWThe optional claims returned in the JWT ID token.
accessTokenCollection (OptionalClaim)RWThe optional claims returned in the JWT access token.
saml2TokenCollection (OptionalClaim)RWThe optional claims returned in the SAML2 token.

OptionalClaim Type

Contains an optional claim associated with an application or a service principal. The idToken, accessToken, and saml2Token properties of the of the OptionalClaims type is a collection of OptionalClaim.

Properties

NameTypeRead/WriteDescription
nameEdm.StringRWThe name of the optional claim.
sourceEdm.StringRWThe source (directory object) of the claim. There are predefined claims and user defined claims from extension properties. If the source value is null, the claim is a predefined optional claim. If the source value is user, the value in the name property is the extension property from the user object.
essentialEdm.BooleanRWIf the value is true, the claim specified by the client is necessary to ensure a smooth authorization experience for the specific task requested by the end user. The default value is false.
additionalPropertiesCollection (Edm.String)RWAdditional boolean properties of the claim. If a property exists in this collection, it modifies the behavior of the optional claim specified in the name property.

PasswordCredential Type

Contains a password credential associated with an application or a service principal. The passwordCredentials property of the ServicePrincipal entity and of the Application entity is a collection of PasswordCredential.

Properties

NameTypeRead/WriteDescription
customKeyIdentifierEdm.Binary
endDateEdm.DateTimeThe date and time at which the password expires.
keyIdEdm.Guid
startDateEdm.DateTimeThe date and time at which the password becomes valid.
valueEdm.String

PasswordProfile Type

Contains the password profile associated with a user. The passwordProfile property of the User entity is a PasswordProfile object.

Properties

NameTypeNotesDescription
passwordEdm.StringWThe password for the user. This property is required when a user is created. It can be updated, but the user will be required to change the password on the next login.

The password must satisfy minimum requirements as specified by the user's PasswordPolicies property. By default, a strong password is required. The password property is write only.
forceChangePasswordNextLoginEdm.BooleanRWtrue if the user must change her password on the next login; otherwise false.

ProvisionedPlan Type

The provisionedPlans property of the User entity and the TenantDetail entity is a collection of ProvisionedPlan.

Properties

NameTypeRead/WriteDescription
capabilityStatusEdm.StringRFor example, "Enabled" or "Deleted".
provisioningStatusEdm.StringRFor example, "Success".
serviceEdm.StringRThe name of the service; for example, "SharePoint", "MicrosoftOffice", or "Exchange".

ProvisioningError Type

The provisioningErrors property of the Contact, User, and Group entities is a collection of ProvisioningError.

Properties

NameTypeRead/WriteDescription
errorDetailEdm.StringRA description of the error.
resolvedEdm.BooleanRtrue if the error was resolved; otherwise, false.
serviceInstanceEdm.StringRThe service instance for which the error occurred.
timestampEdm.DateTimeRThe date and time at which the error occurred.

RequiredResourceAccess Type

Specifies the set of OAuth 2.0 permission scopes and app roles under the specified resource that an application requires access to. The specified OAuth 2.0 permission scopes may be requested by client applications (through the requiredResourceAccess collection) when calling a resource application. The requiredResourceAccess property of the Application entity is a collection of ReqiredResourceAccess.

Important: Requires version 1.5 or newer.

Properties

NameTypeRead/WriteDescription
resourceAppIdEdm.StringRWThe unique identifier for the resource that the application requires access to. This should be equal to the appId declared on the target resource application.
resourceAccessCollection(ResourceAccess)RWThe list of OAuth2.0 permission scopes and app roles that the application requires from the specified resource.

Notes: not nullable.

ResourceAccess Type

Specifies an OAuth 2.0 permission scope or an app role that an application requires. The resourceAccess property of the RequiredResourceAccess type is a collection of ResourceAccess.

Important: Requires version 1.5 or newer.

Properties

NameTypeRead/WriteDescription
idEdm.GuidRWThe unique identifier for one of the OAuth2Permission or AppRole instances that the resource application exposes.

Notes: not nullable.
typeEdm.StringRWSpecifies whether the id property references an OAuth2Permission or an AppRole. Possible values are "scope" or "role".

ServicePlanInfo Type

Contains information about a service plan associated with a subscribed SKU or a license assigned to a user. The servicePlans property of the SubscribedSku and LicenseDetail entity is a collection of ServicePlanInfo.

Properties

NameTypeRead/WriteDescription
appliesToEdm.StringRThe object the service plan can be assigned to. Possible values:
"User" - service plan can be assigned to individual users.
"Company" - service plan can be assigned to the entire tenant.

Notes: Requires version 1.6.
provisioningStatusEdm.StringRPossible values:
"Success" - Service is fully provisioned.
"Disabled" - Service has been disabled.
"PendingInput" - Service is not yet provisioned; awaiting service confirmation.
"PendingActivation" - Service is provisioned but requires explicit activation by administrator (e.g. Intune_O365 service plan)
"PendingProvisioning" - Microsoft has added a new service to the product SKU and it has not been activated in the tenant, yet.

Notes: Requires version 1.6.
servicePlanIdEdm.GuidRThe unique identifier (GUID) of the service plan.
servicePlanNameEdm.StringRThe name of the service plan. For example, "MFA_PREMIUM", "AAD_PREMIUM", or "RMS_S_BASIC".

ServicePrincipalAuthenticationPolicy Type

Contains the authentication policy of a service principal.

Important: Available only in version 2013-11-08; however it is reserved for internal use only and is removed in version 1.5 and newer.

Properties

NameTypeRead/WriteDescription
defaultPolicyEdm.StringRWReserved for internal use only. Do not use. Removed in version 1.5.
allowedPoliciesCollection(Edm.String)RWReserved for internal use only. Do not use. Removed in version 1.5.

Notes: not nullable.

SignInName Type

Contains information about a sign-in name of a local account user in an Azure Active Directory B2C tenant. The signInNames property of the User entity is a collection of SignInName. For more information about Azure Active Directory B2C, see the Azure Active Directory B2C documentation.

Important: Introduced in version 1.6.

Properties

NameTypeRead/WriteDescription
typeEdm.StringRWA string value that can be used to classify user sign-in types in your directory, such as "emailAddress" or "userName".
valueEdm.StringRWThe sign-in used by the local account. Must be unique across the company/tenant. For example, "johnc@example.com".

UserIdentity Type

Contains information about a identity of a social account user in an Azure Active Directory B2C tenant. The userIdentities property of the User entity is a collection of userIdentity. For more information about Azure Active Directory B2C, see the Azure Active Directory B2C documentation.

Important: Introduced in version 1.6.

Properties

NameTypeRead/WriteDescription
issuerEdm.StringRWThe string representation of the identity provider that issued the user identifier, such as facebook.com.
issuerUserIdEdm.BinaryRWThe unique user identifier used by the social identity provider.

VerifiedDomain Type

Specifies a domain for a tenant. The verifiedDomains property of the TenantDetail entity is a collection of VerifiedDomain.

Properties

NameTypeRead/WriteDescription
capabilitiesEdm.StringRFor example, "Email", "OfficeCommunicationsOnline".
defaultEdm.BooleanRtrue if this is the default domain associated with the tenant; otherwise, false.
idEdm.StringRFor example, "00057FFE80187238".
initialEdm.BooleanR
nameEdm.StringRThe domain name; for example, "contoso.onmicrosoft.com"
typeEdm.StringRFor example, "Managed".

Additional Resources

  • Learn more about Graph API supported features, capabilities, and preview features in Graph API concepts
© 2018 Microsoft