Entity and complex type reference | Graph API reference

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.

This article applies to Azure AD Graph API. For similar info related to Microsoft Graph API, see Microsoft Graph REST API v1.0 overview.

Caution

Azure Active Directory (Azure AD) Graph is deprecated and is currently in its retirement path. We recommend that you migrate your apps to Microsoft Graph.

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

Name Type Supports Description
addIns Collection(AddIn) POST, GET, PATCH Defines 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.
appId Edm.String in version 1.5

Edm.Guid in previous versions
GET ($filter) The unique identifier for the application.
appRoles Collection(AppRole) POST, GET, PATCH The 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.
availableToOtherTenants Edm.Boolean POST, GET ($filter), PATCH true if the application is shared with other tenants; otherwise, false.
deletionTimestamp Edm.DateTime GET The 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.
displayName Edm.String POST (Required), GET, PATCH The display name for the application.
errorUrl Edm.String POST, GET, PATCH
groupMembershipClaims Edm.String POST, GET, PATCH A 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.
homepage Edm.String POST, GET, PATCH The URL to the application's homepage.
identifierUris Collection(Edm.String) POST, GET ($filter), PATCH User-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.
keyCredentials Collection(KeyCredential) POST, GET, PATCH The collection of key credentials associated with the application

Notes: not nullable
knownClientApplications Collection(Edm.Guid) POST, GET, PATCH Client 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.
logoutUrl Edm.String POST, GET, PATCH
mainLogo Edm.Stream POST, GET, PATCH The main logo for the application.

Notes: not nullable
oauth2AllowImplicitFlow Edm.Boolean POST, GET, PATCH Specifies whether this web application can request OAuth2.0 implicit flow tokens. The default is false.

Notes: Requires version 1.5, not nullable.
oauth2AllowUrlPathMatching Edm.Boolean POST, GET, PATCH Specifies 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.
oauth2Permissions Collection(OAuth2Permission) POST, GET, PATCH The 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.
oauth2RequiredPostResponse Edm.Guid POST, GET, PATCH Specifies 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.
objectId Edm.Guid GET The unique identifier for the application. Inherited from DirectoryObject.

Notes: key, immutable, not nullable, unique
objectType Edm.String GET A string that identifies the object type. For applications the value is always "Application". Inherited from DirectoryObject.
optionalClaims OptionalClaims POST, GET, PATCH The optional claims returned in the token by the security token service for this specific app.
passwordCredentials Collection(PasswordCredential) POST, GET, PATCH The collection of password credentials associated with the application.

Notes: not nullable
publicClient Edm.Boolean POST, GET Specifies whether this application is a public client (such as an installed application running on a mobile device). Default is false.
recordConsentConditions Edm.String GET Do not use. May be removed in future versions

Notes: Requires version 1.6.
replyUrls Collection(Edm.String) POST, GET, PATCH Specifies 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
requiredResourceAccess Collection(RequiredResourceAccess) POST, GET, PATCH Specifies 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.
samlMetadataUrl Edm.String POST, GET, PATCH The URL to the SAML metadata for the application.

Navigation Properties

Name To Multiplicity
(From/To)
Description
extensionProperties ExtensionProperty */* The extension properties associated with the application. Requires 1.5 or newer.
owners DirectoryObject */* 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.
policies Policy */* Policies assigned to the application.
serviceEndpoints ServiceEndpoint 1/* 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

Name Type Supports Description
creationTimestamp Edm.DateTime GET The time when the grant was created.
deletionTimestamp Edm.DateTime GET This property is not valid for app role assignment and always returns null. Inherited from DirectoryObject.

Notes: Requires version 1.5 or newer.
id Edm.Guid POST (Required), GET, PATCH The 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.
principalDisplayName Edm.String GET The display name of the principal that was granted the access.
objectId Edm.String GET The unique identifier for the application role assignment. Inherited from DirectoryObject.

Notes: key, immutable, not nullable, unique.
objectType Edm.String GET A string that identifies the object type. For application role assignments the value is always "AppRoleAssignment". Inherited from DirectoryObject.
principalId Edm.Guid POST (Required), GET, PATCH The unique identifier (objectId) for the principal being granted the access.

Notes: required.
principalType Edm.String GET The type of principal. This can either be "User", "Group" or "ServicePrincipal".
resourceDisplayName Edm.String GET The display name of the resource to which the assignment was made.
resourceId Edm.Guid POST (Required), GET, PATCH The 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

Name Type Supports Description
city Edm.String GET ($filter), PATCH The city in which the contact is located.
country Edm.String GET ($filter), PATCH The country/region in which the contact is located.
deletionTimestamp Edm.DateTime GET This property is not valid for contacts and always returns null. Inherited from DirectoryObject.

Notes: Requires version 1.5 or newer.
department Edm.String GET ($filter), PATCH The name for the department in which the contact works.
dirSyncEnabled Edm.Boolean GET ($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).
displayName Edm.String GET ($filter), PATCH The display name for the contact.
facsimileTelephoneNumber Edm.String GET, PATCH The telephone number of the contact's business fax machine.
givenName Edm.String GET ($filter), PATCH The given name (first name) of the contact.
jobTitle Edm.String GET ($filter), PATCH The contact's job title.
lastDirSyncTime Edm.DateTime GET ($filter) Indicates the last time at which the object was synced with the on-premises directory.
mail Edm.String GET ($filter) The SMTP address for the contact, for example, "jeff@contoso.onmicrosoft.com".
mailNickname Edm.String GET ($filter), PATCH The mail alias for the contact.
mobile Edm.String GET, PATCH The primary cellular telephone number for the contact.
objectId Edm.String GET The unique identifier for the contact. Inherited from DirectoryObject.

Notes: key, immutable, not nullable, unique.
objectType Edm.String GET A string that identifies the object type. For contacts the value is always "Contact". Inherited from DirectoryObject.
physicalDeliveryOfficeName Edm.String GET, PATCH The office location in the contact's place of business.
postalCode Edm.String GET, PATCH The 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.
provisioningErrors Collection(ProvisioningError) GET, PATCH A collection of error details that are preventing this contact from being provisioned successfully.

Note: not nullable
proxyAddresses Collection(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.
sipProxyAddress Edm.String GET Specifies the voice over IP (VOIP) session initiation protocol (SIP) address for the contact.

Notes: Requires version 1.5 or newer.
state Edm.String GET ($filter), PATCH The state or province in the contact's address.
streetAddress Edm.String GET, PATCH The street address of the contact's place of business.
surname Edm.String GET ($filter), PATCH The contact's surname (family name or last name).
telephoneNumber Edm.String GET, PATCH The primary telephone number of the contact's place of business.
thumbnailPhoto Edm.Stream GET, PATCH A thumbnail photo to be displayed for the contact.

Note: not nullable

Navigation Properties

Name To Multiplicity
(From/To)
Description
manager DirectoryObject

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

HTTP Methods: GET, PUT, DELETE
directReports DirectoryObject

(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
memberOf DirectoryObject

(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

Name Type Supports Description
contractType Edm.String GET Type 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.
customerContextId Edm.Guid GET ($filter) The unique identifier for the customer tenant referenced by this partnership. Corresponds to the objectId property of the customer tenant's TenantDetail object.
defaultDomainName Edm.String GET ($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.
deletionTimestamp Edm.DateTime GET This property is not valid for contracts and always returns null. Inherited from DirectoryObject.

Notes: Requires version 1.5 or newer.
displayName Edm.String GET ($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.
objectType Edm.String GET A string that identifies the object type. The value is always “Contract”. Inherited from DirectoryObject.
objectId Edm.String GET The 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

Name Type Supports Description
accountEnabled Edm.Boolean POST (required), GET ($filter), PATCH true if the account is enabled; otherwise, false. Default is true.
alternativeSecurityIds Collection(AlternativeSecurityId) POST (required), GET ($filter), PATCH Notes: 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.
approximateLastLogonTimeStamp Edm.DateTime POST, GET, PATCH 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.
deletionTimestamp Edm.DateTime GET This property is not valid for devices and always returns null. Inherited from DirectoryObject.

Notes: Requires version 1.5 or newer.
deviceId Edm.Guid POST (Required), GET ($filter), PATCH Unique identifier set by Azure Device Registration Service at the time of registration.
deviceObjectVersion Edm.Int32 POST, GET, PATCH For internal use only.
deviceOSType Edm.String POST (Required), GET, PATCH The type of operating system on the device. Required.
deviceOSVersion Edm.String POST (Required), GET, PATCH The version of the operating system on the device. Required.
devicePhysicalIds Collection(Edm.String) POST, GET ($filter), PATCH Notes: For internal use. Not nullable.
dirSyncEnabled Edm.Boolean GET ($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).
displayName Edm.String POST (Required), GET ($filter), PATCH The display name for the device. Required.
isCompliant Edm.Boolean POST, GET, PATCH true 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.
IsManaged Edm.Boolean POST, GET, PATCH true 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.
lastDirSyncTime Edm.DateTime GET ($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.
objectId Edm.String GET The unique identifier for the device. Inherited from DirectoryObject.

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

Navigation Properties

Name To Multiplicity
(From/To)
Description
registeredOwners User */* Users that are registered owners of the device.
registeredUsers User */* 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

Name Type Supports Description
associationType Edm.String GET A string that identifies the association type to which the change applies. The value is either "Member" or "Manager".
deletionTimestamp Edm.DateTime GET This property is not valid for directory link change objects and always returns null. Inherited from DirectoryObject.

Notes: Requires version 1.5 or newer.
objectId Edm.String GET The 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
objectType Edm.String GET A string that identifies the object type. For DirectoryLinkChange objects, the value is always "DirectoryLinkChange". DirectoryObject
sourceObjectId Edm.String GET The object ID for the source object; for example, "7373b0af-d462-406e-ad26-f2bc96d823d8".
sourceObjectType Edm.String GET A string that identifies the source object type; this will be one of the following: "Group", "User", or "Contact".
sourceObjectUri Edm.String GET The URI for the source object; for example, "https://graph.windows.net/contoso.com/groups/7373b0af-d462-406e-ad26-f2bc96d823d8".
targetObjectId Edm.String GET The object ID for the target object; for example, "dca803ab-bf26-4753-bf20-e1c56a9c34e2".
targetObjectType Edm.String GET A string that identifies the source object type; this will be one of the following: "Group", "User", or "Contact".
targetObjectUri Edm.String GET The 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

Name Type Supports Description
deletionTimestamp Edm.DateTime GET The 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.
objectId Edm.String GET A Guid that is the unique identifier for the object; for example, 12345678-9abc-def0-1234-56789abcde.

Notes: key, immutable, not nullable, unique.
objectType Edm.String GET A string that identifies the object type. For example, for groups the value is always "Group".

Navigation Properties

Name To Multiplicity
(From/To)
Description
createdObjects DirectoryObject */* The directory objects that were created by the current object. Read only. Requires version 2013-11-08 or newer.
createdOnBehalfOf DirectoryObject */0..1 The directory object that that this object was created on behalf of. Read only. Requires version 2013-11-08 or newer.
manager DirectoryObject */0..1 This object's manager. Valid on users and contacts. Returns a user or a contact.
directReports DirectoryObject */* Users and contacts that report to this object. Valid on users and contacts. Returns users and contacts. Read only.
members DirectoryObject */* 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.
memberOf DirectoryObject */* 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.
ownedObjects DirectoryObject */* The directory objects that are owned by the current object. Read only. Requires version 2013-11-08 or newer.
owners DirectoryObject */* 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

Name Type Supports Description
deletionTimestamp Edm.DateTime GET This property is not valid for directory roles and always returns null. Inherited from DirectoryObject.

Notes: Requires version 1.5 or newer.
description Edm.String GET The description for the directory role.
displayName Edm.String GET The display name for the directory role.
isSystem Edm.Boolean GET true if the role is a system role; otherwise, false.
objectId Edm.String GET The unique identifier for the directory role. Inherited from DirectoryObject.

Notes: key, immutable, not nullable, unique.
objectType Edm.String GET A 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".
roleDisabled Edm.Boolean GET true if the directory role is disabled; otherwise, false.
roleTemplateId String POST (Required), GET The 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

Name To Multiplicity
(From/To)
Description
members DirectoryObject

(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

Name Type Supports Description
description Edm.String GET The description to set for the directory role.
deletionTimestamp Edm.DateTime GET This property is not valid for directory role templates and always returns null. Inherited from DirectoryObject.

Notes: Requires version 1.5 or newer.
displayName Edm.String GET The display name to set for the directory role.
objectId Edm.String GET The 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.
objectType Edm.String GET A 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

Name Type Supports Description
authenticationType Edm.String GET Indicates what authentication type the domain is configured for. The value is either "Managed" or "Federated".
availabilityStatus Edm.String GET This 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".
isAdminManaged Edm.Boolean GET false, if the DNS record management of the domain has been delegated to Office 365. Otherwise, true.

Notes: not nullable
isDefault Edm.Boolean GET, PATCH Indicates 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
isInitial Edm.Boolean GET Indicates 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
isRoot Edm.Boolean GET For subdomains, this represents the root domain. Only root domains need to be verified, and all subdomains will be automatically verified.

Notes: not nullable
isVerified Edm.Boolean GET Indicates whether this domain has completed domain ownership verification or not.

Notes: not nullable
name Edm.String POST (Required), GET ($filter) The fully qualified name of the domain.

Notes: key, immutable, not nullable, unique
supportedServices Collection(Edm.String) GET, PATCH The 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

Name To Multiplicity
(From/To)
Description
serviceConfigurationRecords DomainDnsRecord */* 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.
verificationDnsRecords DomainDnsRecord */* 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

Name Type Supports Description
dnsRecordId Edm.Guid GET Unique identifier assigned to this entity.

Notes: not nullable
isOptional Edm.Boolean GET Indicates 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
label Edm.String GET Indicates the value to use when configuring the name of the DNS record at the DNS host.
recordType Edm.String GET Indicates what type of DNS record this entity represents. The value can be one of the following:
  • "CName"
  • "Mx"
  • "Srv"
  • "Txt"


Notes: key
supportedService Edm.String GET Indicates 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"
ttl Edm.Int32 GET Indicates 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

Name Type Supports Description
canonicalName Edm.String GET Indicates the value to use when configuring the canonical name of the CNAME record at the DNS host.
dnsRecordId Edm.Guid GET Unique identifier assigned to this entity.

Notes: not nullable
isOptional Edm.Boolean GET Indicates 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
label Edm.String GET Indicates the value to use when configuring the name of the CNAME record at the DNS host.
recordType Edm.String GET Indicates what type of DNS record this entity represents. The value is always "CName".

Notes: key
supportedService Edm.String GET Indicates 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"
ttl Edm.Int32 GET Indicates 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

Name Type Supports Description
dnsRecordId Edm.Guid GET Unique identifier assigned to this entity.

Notes: not nullable
isOptional Edm.Boolean GET Indicates 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
label Edm.String GET Value to use when configuring the Alias/Host/Name property of the MX record at the DNS host.
mailExchange Edm.String GET Value to use when configuring the Answer/Destination/Value of the MX record at the DNS host.
recordType Edm.String GET Indicates what type of DNS record this entity represents. The value is always "Mx".

Notes: key
preference Edm.Int32 GET Value to use when configuring the Preference/Priority property of the MX record at the DNS host.
supportedService Edm.String GET Indicates 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"
ttl Edm.Int32 GET Value 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

Name Type Supports Description
dnsRecordId Edm.Guid GET Unique identifier assigned to this entity.

Notes: not nullable
isOptional Edm.Boolean GET Indicates 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
label Edm.String GET Value to use when configuring the Name property of the SRV record at the DNS host.
nameTarget Edm.String GET Value to use when configuring the Target property of the SRV record at the DNS host.
port Edm.Int32 GET Value to use when configuring the Port property of the SRV record at the DNS host.
priority Edm.Int32 GET Value to use when configuring the Priority property of the SRV record at the DNS host.
protocol Edm.String GET Value to use when configuring the Protocol property of the SRV record at the DNS host.
recordType Edm.String GET Indicates what type of DNS record this entity represents. The value is always "Srv".

Notes: key
Service Edm.String GET Value to use when configuring the Service property of the SRV record at the DNS host.
supportedService Edm.String GET Indicates 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"
ttl Edm.Int32 GET Value to use when configuring the Time-To-Live property of the SRV record at the DNS host.

Notes: not nullable
weight Edm.Int32 GET Value 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

Name Type Supports Description
dnsRecordId Edm.Guid GET Unique identifier assigned to this entity.

Notes: not nullable
isOptional Edm.Boolean GET Indicates 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
label Edm.String GET Value to use when configuring the Alias/Host/Name property of the MX record at the DNS host.
recordType Edm.String GET Indicates what type of DNS record this entity represents. The value is always "Mx".

Notes: key
supportedService Edm.String GET Indicates 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"
text Edm.String GET
ttl Edm.Int32 GET Value (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

Name Type Supports Description
description Edm.String GET Provides 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

Name Type Supports Description
appDisplayName Edm.String GET
dataType Edm.String POST, GET, PATCH Specifies 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.
deletionTimestamp Edm.DateTime GET This property is not valid for extension properties and always returns null. Inherited from DirectoryObject.
objectId Edm.String GET The unique identifier for the extension property. Inherited from DirectoryObject.

Notes: key, immutable, not nullable, unique.
objectType Edm.String GET A string that identifies the object type. For extension properties the value is always "ExtensionProperty". Inherited from DirectoryObject.
name Edm.String POST, GET, PATCH Specifies the display name for the directory extension property.

Notes: not nullable.
isSyncedFromOnPremises Edm.Boolean GET Indicates whether the extension property is synced from the on premises directory.

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

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

Name Type Supports Description
deletionTimestamp Edm.DateTime GET This property is not valid for groups and always returns null. Inherited from DirectoryObject.

Notes: Requires version 1.5 or newer.
description Edm.String POST, GET, PATCH An optional description for the group.
dirSyncEnabled Edm.Boolean GET ($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).
displayName Edm.String POST (Required), GET ($filter), PATCH The display name for the group. This property is required when a group is created and it cannot be cleared during updates.
lastDirSyncTime Edm.DateTime GET ($filter) Indicates the last time at which the object was synced with the on-premises directory.
mail Edm.String GET ($filter) The SMTP address for the group, for example, "serviceadmins@contoso.onmicrosoft.com".
mailEnabled Edm.Boolean POST (Required), GET, PATCH Specifies 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.
mailNickname Edm.String POST (Required), GET ($filter), PATCH The mail alias for the group. This property must be specified when a group is created.
objectId Edm.String GET The unique identifier for the group. Inherited from DirectoryObject.

Notes: key, immutable, not nullable, unique.
objectType Edm.String GET A string that identifies the object type. For groups the value is always "Group". Inherited from DirectoryObject.
onPremisesSecurityIdentifier String GET Contains 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.
provisioningErrors Collection(ProvisioningError) GET A collection of error details that are preventing this group from being provisioned successfully.

Notes: not nullable.
preferredLanguage String POST, GET, PATCH The preferred language for an Office 365 group. Should follow ISO 639-1 Code; for example "en-US".
proxyAddresses Collection(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.
securityEnabled Edm.Boolean POST (Required), GET ($filter), PATCH Specifies 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.
theme String POST, GET, PATCH Specifies an Office 365 group's color theme. Possible values are Teal, Purple, Green, Blue, Pink, Orange or Red.

Navigation Properties

Name To To Multiplicity Description
members DirectoryObject

(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)
memberOf DirectoryObject

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

HTTP Methods: GET (supported for all groups)
owners DirectoryObject */* 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)
appRoleAssignments DirectoryObject */* Contains the set of applications that a group is assigned to.

Notes: Requires version 1.5 or newer.
extensionProperties DirectoryObject */* 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

Property Type Supports Description
objectId Edm.String GET The unique identifier for the license detail object.

Notes: key, not nullable.
servicePlans Collection(ServicePlanInfo) GET Information about the service plans assigned with the license.

Notes: not nullable.
skuId Edm.Guid GET Unique identifier (GUID) for the service SKU. Equal to the skuId property on the related SubscribedSku object.
skuPartNumber Edm.String GET Unique 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

Property Type Supports Description
clientId Edm.String POST, GET Specifies the objectId of the service principal granted consent to impersonate the user when accessing the resource (represented by the resourceId).
consentType Edm.String POST, GET Specifies 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".
expiryTime Edm.DateTime POST, GET, PATCH Reserved. Returns null. Do not use.
objectId Edm.String GET The unique identifier for the permission scope.

Notes: key, not nullable.
principalId Edm.String POST, GET If 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.
resourceId Edm.String POST, GET Specifies the objectId of the resource service principal to which access has been granted.
scope Edm.String POST, GET, PATCH Specifies the value of the scope claim that the resource application should expect in the OAuth 2.0 access token.
startTime Edm.DateTime POST, GET Reserved. 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.
Property Type Supports Description
definition Edm.String POST, GET The string version of the specific policy. See the information regarding the format of this string in the sections below.
displayName Edm.String POST, GET, PATCH A custom name for the policy.
IsOrganizationDefault Edm.Boolean POST, GET, PATCH If 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.
type Edm.String POST, GET Specifies the type of policy. Currently must be TokenLifetimePolicy or TokenIssuancePolicy.

Navigation Properties

Name To Multiplicity
(From/To)
Description
appliesTo DirectoryObject */* 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".

Property Type Description Min Value Max Value Default Value
AccessTokenLifetime String Controls how long both access and ID tokens are considered valid. 10 minutes 1 day 1 hour
MaxInactiveTime String Controls 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 minutes 90 days 14 days
MaxAgeSingleFactor String Controls 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 minutes until-revoked 365 days or until-revoked
MaxAgeMultiFactor String Controls 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 minutes until-revoked 365 days or until-revoked
MaxAgeSessionSingleFactor String Controls 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 MultiFactorSessionTokenMaxAge 10 minutes until-revoked 365 or until-revoked
MaxAgeSessionMultiFactor String Controls 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 minutes until-revoked 365 or until-revoked
Version Integer Set value of 1. Required. None None None

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.

Property Type Description Values Default Value
SamlTokenVersion String Controls the version of the SAML token issued. 1.1
2.0
2.0
SigningAlgorithm String Controls 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
TokenResponseSigningPolicy String Controls 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
Version Integer The version of the token issuance policy. Required. 1 None

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

Property Type Supports Description
capability Edm.String POST (Required), GET A text identifier for the service's capability. Examples are "Documents" and "Mail".
deletionTimestamp Edm.DateTime GET This property is not valid for service endpoints and always returns null. Inherited from DirectoryObject.
objectId Edm.String GET The unique identifier for the service endpoint. Inherited from DirectoryObject.

Notes: key, immutable, not nullable, unique.
objectType Edm.String GET A string that identifies the object type. For service endpoints the value is always "ServiceEndpoint". Inherited from DirectoryObject.
serviceId Edm.String POST, GET The identifier of the service
serviceName Edm.String POST, GET The display name of the service.
Uri Edm.String POST (Required), GET Uri of the service’s endpoint.
resourceId Edm.String POST, GET An 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

Name Type Supports Description
accountEnabled Edm.Boolean POST, GET ($filter), PATCH true if the service principal account is enabled; otherwise, false.
addIns Collection(AddIn) GET 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 the context of a document the user is working on.

Notes: Requires version 1.6.
appDisplayName Edm.String GET The display name exposed by the associated application.
appId Edm.Guid POST (Required), GET ($filter), PATCH The unique identifier for the associated application (its appId property).
appOwnerTenantId Edm.Guid GET
appRoleAssignmentRequired Edm.Boolean POST, GET, PATCH Specifies 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.
appRoles Collection(AppRole) GET The 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.
authenticationPolicy ServicePrincipalAuthenticationPolicy GET Reserved for internal use only. Do not use. Removed in version 1.5.

Notes: Available in version 2013-11-08 only.
deletionTimestamp Edm.DateTime GET This property is not valid for service principals and always returns null. Inherited from DirectoryObject.

Notes: Requires version 1.5 or newer.
displayName Edm.String POST, GET ($filter), PATCH The display name for the service principal.
errorUrl Edm.String POST, GET, PATCH
homepage Edm.String POST, GET, PATCH The URL to the homepage of the associated application.
keyCredentials Collection(KeyCredential) POST, GET, PATCH The collection of key credentials associated with the service principal.

Notes: not nullable.
logoutUrl Edm.String POST, GET, PATCH
oauth2Permissions Collection(OAuth2Permission) GET The 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.
objectId Edm.String GET The unique identifier for the service principal. Inherited from DirectoryObject.

Notes: key, immutable, not nullable, unique.
objectType Edm.String GET A string that identifies the object type. For service principals the value is always "ServicePrincipal". Inherited from DirectoryObject.
passwordCredentials Collection(PasswordCredential) POST, GET, PATCH The collection of password credentials associated with the service principal.

Notes: not nullable.
preferredTokenSigningKeyThumbprint Edm.String GET Reserved 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.
publisherName Edm.String POST, GET ($filter), PATCH The display name of the tenant in which the associated application is specified.
replyUrls Collection(Edm.String) POST, GET, PATCH The 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.
samlMetadataUrl Edm.String POST, GET, PATCH
servicePrincipalNames Collection(Edm.String) POST, GET ($filter), PATCH Based 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.
tags Collection(Edm.String) POST, GET ($filter), PATCH

Notes: not nullable.

Navigation Properties

Name To Multiplicity
(From/To)
Description
appRoleAssignedTo AppRoleAssignment */* Principals (users, groups, and service principals) that are assigned to this service principal. Requires version 1.5 or newer.
appRoleAssignments AppRoleAssignment */* Applications that the service principal is assigned to. Requires version 1.5 or newer.
createdObjects DirectoryObject */* Directory objects created by this service principal. Inherited from DirectoryObject. Requires version 2013-11-08 or newer.
memberOf DirectoryObject

(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
oauth2PermissionGrants OAuth2PermissionGrant */* User impersonation grants associated with this service principal. Requires version 1.5 or newer.
ownedObjects DirectoryObject */* Directory objects that are owned by this service principal. Inherited from DirectoryObject. Requires version 2013-11-08 or newer.
owners DirectoryObject */* 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.
permissions Permission */* 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.
policies Policy */* Policies assigned to the service principal.
serviceEndpoints ServiceEndpoint 1/* 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

Property Type Supports Description
appliesTo Edm.String GET For example, "User" or "Company".

Notes: Requires version 1.6.
capabilityStatus Edm.String GET For example, "Enabled".
consumedUnits Edm.Int32 GET The number of licenses that have been assigned.
objectId Edm.String GET The unique identifier for the subscribed sku object.

Notes: key, not nullable.
prepaidUnits LicenseUnitsDetail GET Information about the number and status of prepaid licenses.
servicePlans Collection(ServicePlanInfo) GET Information about the service plans that are available with the SKU.

Notes: not nullable.
skuId Edm.Guid GET The unique identifier (GUID) for the service SKU.
skuPartNumber Edm.String GET The 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

Name Type Supports Description
assignedPlans Collection(AssignedPlan) GET The collection of service plans associated with the tenant.

Notes: not nullable.
city Edm.String GET
companyLastDirSyncTime Edm.DateTime GET The time and date at which the tenant was last synced with the on-premise directory.
country Edm.String GET
countryLetterCode Edm.String GET
deletionTimestamp Edm.DateTime GET This property is not valid for tenants and always returns null. Inherited from DirectoryObject.

Notes: Requires version 1.5 or newer.
dirSyncEnabled Edm.Boolean GET 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).
displayName Edm.String GET The display name for the tenant.
marketingNotificationEmails Collection(Edm.String) GET, PATCH

Notes: not nullable.
objectId Edm.String GET The unique identifier for the tenant. Inherited from DirectoryObject.

Notes: key, immutable, not nullable, unique.
objectType Edm.String GET A string that identifies the object type. For tenants the value is always "Company". Inherited from DirectoryObject.
postalCode Edm.String GET
preferredLanguage Edm.String GET
provisionedPlans Collection(ProvisionedPlan) GET

Notes: not nullable.
provisioningErrors Collection(ProvisioningError) GET

Notes: not nullable.
state Edm.String GET
street Edm.String GET
technicalNotificationMails Collection(Edm.String) GET, PATCH

Notes: not nullable.
telephoneNumber Edm.String GET
tenantType Edm.String GET

Notes: removed in version 1.5 and newer.
verifiedDomains Collection(VerifiedDomain) GET The collection of domains associated with this tenant.

Notes: not nullable.

Navigation Properties

Name To To Multiplicity Description
trustedCAsForPasswordlessAuth TrustedCAsForPasswordlessAuth 1/1 The 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

Name Type Supports Description
id Edm.String GET Unique identifier.

Notes: key, not nullable.
certificateAuthorities Collection(CertificateAuthorityInformation) POST (Required), GET, PATCH Collection 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

Name Type Supports Description
accountEnabled Edm.Boolean POST (Required), GET ($filter), PATCH true if the account is enabled; otherwise, false. This property is required when a user is created.
assignedLicenses Collection(AssignedLicense) POST, GET, PATCH The licenses that are assigned to the user.

Notes: not nullable.
assignedPlans Collection(AssignedPlan) GET The plans that are assigned to the user.

Notes: not nullable.
city Edm.String POST, GET ($filter), PATCH The city in which the user is located.
country Edm.String POST, GET ($filter), PATCH The country/region in which the user is located; for example, "US" or "UK".
creationType Edm.String POST (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.
deletionTimestamp Edm.DateTime GET This property is not valid for users and always returns null. Inherited from DirectoryObject.

Notes: Requires version 1.5 or newer.
department Edm.String POST, GET ($filter), PATCH The name for the department in which the user works.
dirSyncEnabled Edm.Boolean GET ($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).
displayName Edm.String POST (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.
employeeId Edm.String POST, GET ($filter), PATCH The employee identifier assigned to the user by the organization.
facsimileTelephoneNumber Edm.String POST, GET, PATCH The telephone number of the user's business fax machine.
givenName Edm.String POST, GET ($filter), PATCH The given name (first name) of the user.
immutableId Edm.String POST (Required if using a federated domain for the UPN), GET ($filter), PATCH This 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.
jobTitle Edm.String POST, GET ($filter), PATCH The user's job title.
lastDirSyncTime Edm.DateTime GET ($filter) Indicates the last time at which the object was synced with the on-premises directory; for example: "2013-02-16T03:04:54Z"
mail Edm.String POST, GET ($filter) The SMTP address for the user, for example, "jeff@contoso.onmicrosoft.com".
mailNickname Edm.String POST (Required for work or school accounts), GET ($filter), PATCH The mail alias for the user. This property is required when you create a work or school account; it is optional for a local account.
mobile Edm.String POST, GET, PATCH The primary cellular telephone number for the user.
objectId Edm.Guid GET The unique identifier for the user. Inherited from DirectoryObject.

Notes: key, immutable, not nullable, unique.
objectType Edm.String GET A string that identifies the object type. For users the value is always "User". Inherited from DirectoryObject.
onPremisesSecurityIdentifier Edm.String GET Contains 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.
otherMails Collection(Edm.String) POST, GET ($filter), PATCH A 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.
passwordPolicies Edm.String POST, GET, PATCH Specifies 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".
passwordProfile PasswordProfile POST (Required), PATCH Specifies 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.
physicalDeliveryOfficeName Edm.String POST, GET, PATCH The office location in the user's place of business.
postalCode Edm.String POST, GET, PATCH The 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.
preferredLanguage Edm.String POST, GET, PATCH The preferred language for the user. Should follow ISO 639-1 Code; for example "en-US".
provisionedPlans Collection(ProvisionedPlan) GET The plans that are provisioned for the user.

Notes: not nullable.
provisioningErrors Collection(ProvisioningError) GET A collection of error details that are preventing this user from being provisioned successfully.
proxyAddresses Collection(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.
refreshTokensValidFromDateTime Edm.DateTime POST, GET, PATCH Any 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.
showInAddressList Edm.Boolean POST, GET, PATCH true 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.
signInNames Collection(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.
sipProxyAddress Edm.String GET Specifies the voice over IP (VOIP) session initiation protocol (SIP) address for the user.

Notes: Requires version 1.5 or newer.
state Edm.String POST, GET ($filter), PATCH The state or province in the user's address.
streetAddress Edm.String POST, GET, PATCH The street address of the user's place of business.
surname Edm.String POST, GET ($filter), PATCH The user's surname (family name or last name).

Notes: filterable, must be between 1 and 64 characters.
telephoneNumber Edm.String POST, GET, PATCH The primary telephone number of the user's place of business.
thumbnailPhoto Edm.Stream POST, GET, PATCH A thumbnail photo to be displayed for the user.

Notes: not nullable.
usageLocation Edm.String POST, GET ($filter), PATCH A 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.
userIdentities Collection(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.
userPrincipalName Edm.String POST (Required for work or school accounts), GET ($filter), PATCH The 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.
userType Edm.String POST, GET ($filter), PATCH A 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

Name To Multiplicity
(From/To)
Description
manager DirectoryObject

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

HTTP Methods: GET, PUT, DELETE
directReports DirectoryObject

(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
licenseDetails LicenseDetail */*

Notes: Requires version 1.6 or later.
memberOf DirectoryObject

(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
ownedDevices Device */* Devices that are owned by the user.
permissions Permission */* 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.

registeredDevices Device */* Devices that are registered for the user.
createdObjects DirectoryObject */* Directory objects that were created by the user. Requires version 2013-11-08 or newer.
ownedObjects DirectoryObject */* Directory objects that are owned by the user. Requires version 2013-11-08 or newer.
appRoleAssignments AppRoleAssignment */* The set of applications that this user is assigned to. Requires version 1.5 or newer.

HTTP Methods: GET, POST, DELETE
oauth2PermissionGrants OAuth2PermissionGrant */* 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

Name Type Read/Write Description
id Edm.Guid R A unique identifier within the addins collection on a specific Application.
type Edm.String RW The unique name for the functionality exposed by the app.
properties Collection(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

Name Type Read/Write Description
identityProvider Edm.String
key Edm.Binary
type Edm.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

Name Type Read/Write Description
allowedMemberTypes Collection(Edm.String) RW Specifies 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.
description Edm.String RW Permission help text that appears in the admin app assignment and consent experiences.
displayName Edm.String RW Display name for the permission that appears in the admin consent and app assignment experiences.
id Edm.Guid RW Unique role identifier inside the appRoles collection.
isEnabled Edm.Boolean RW When 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.
value Edm.String RW Specifies 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

Name Type Read/Write Description
disabledPlans Collection(Edm.Guid) R A collection of the unique identifiers for plans that have been disabled.

Notes: not nullable.
skuId Edm.Guid R The 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

Name Type Read/Write Description
assignedTimestamp Edm.DateTime R The date and time at which the plan was assigned; for example: 2013-01-02T19:32:30Z.
capabilityStatus Edm.String R For example, "Enabled".
service Edm.String R The name of the service; for example, "SharePoint", "MicrosoftOffice", or "Exchange".
servicePlanId Edm.Guid R A 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

Name Type Read/Write Description
authorityType Edm.String RW (Required on POST) Required. Must be set to one of two possible values: “RootAuthority” or “IntermediateAuthority”. It is used while validating certificates during authentication.
crlDistributionPoint Edm.String RW Certificate Revocation List (CRL) distribution points hold files which store the serial numbers of all certificates that have been revoked. This is typically a URI.
deltaCrlDistributionPoint Edm.String RW A URI that contains the list of all revoked certificates since the last time a full CRL was created.
trustedCertificate Edm.Binary RW (Required on POST) Required. The public certificate in binary form.
trustedIssuer Edm.String R Read only. Calculated from the trustedCertificate value.
trustedIssuerSki Edm.String R Read 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

Name Type Read/Write Description
customKeyIdentifier Edm.Binary
endDate Edm.DateTime The date and time at which the credential expires.
keyId Edm.Guid The unique identifier (GUID) for the key.
startDate Edm.DateTime The date and time at which the credential becomes valid.
type Edm.String The type of key credential; for example, "Symmetric".
usage Edm.String A string that describes the purpose for which the key can be used; for example, "Verify".
value Edm.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

Name Type Read/Write Description
key Edm.String RW The key in the key value pair.
value Edm.String RW The 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

Name Type Read/Write Description
enabled Edm.Int32 R The number of units that are enabled.
suspended Edm.Int32 R The number of units that are suspended.
warning Edm.Int32 R The 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

Name Type Read/Write Description
adminConsentDescription Edm.String RW Permission help text that appears in the admin consent and app assignment experiences.
adminConsentDisplayName Edm.String RW Display name for the permission that appears in the admin consent and app assignment experiences.
id Edm. Guid RW Unique scope permission identifier inside the oauth2Permissions collection.
isEnabled Edm.Boolean RW When 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.
type Edm.String RW Specifies 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".
userConsentDescription Edm.String RW Permission help text that appears in the end user consent experience.
userConsentDisplayName Edm.String RW Display name for the permission that appears in the end user consent experience.
value Edm.String RW The 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

Name Type Read/Write Description
idToken Collection (OptionalClaim) RW The optional claims returned in the JWT ID token.
accessToken Collection (OptionalClaim) RW The optional claims returned in the JWT access token.
saml2Token Collection (OptionalClaim) RW The 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

Name Type Read/Write Description
name Edm.String RW The name of the optional claim.
source Edm.String RW The 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.
essential Edm.Boolean RW If 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.
additionalProperties Collection (Edm.String) RW Additional 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

Name Type Read/Write Description
customKeyIdentifier Edm.Binary
endDate Edm.DateTime The date and time at which the password expires.
keyId Edm.Guid
startDate Edm.DateTime The date and time at which the password becomes valid.
value Edm.String

PasswordProfile Type

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

Properties

Name Type Notes Description
password Edm.String W The 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.
forceChangePasswordNextLogin Edm.Boolean RW true 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

Name Type Read/Write Description
capabilityStatus Edm.String R For example, "Enabled" or "Deleted".
provisioningStatus Edm.String R For example, "Success".
service Edm.String R The 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

Name Type Read/Write Description
errorDetail Edm.String R A description of the error.
resolved Edm.Boolean R true if the error was resolved; otherwise, false.
serviceInstance Edm.String R The service instance for which the error occurred.
timestamp Edm.DateTime R The 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

Name Type Read/Write Description
resourceAppId Edm.String RW The unique identifier for the resource that the application requires access to. This should be equal to the appId declared on the target resource application.
resourceAccess Collection(ResourceAccess) RW The 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

Name Type Read/Write Description
id Edm.Guid RW The unique identifier for one of the OAuth2Permission or AppRole instances that the resource application exposes.

Notes: not nullable.
type Edm.String RW Specifies 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

Name Type Read/Write Description
appliesTo Edm.String R The 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.
provisioningStatus Edm.String R Possible 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.
servicePlanId Edm.Guid R The unique identifier (GUID) of the service plan.
servicePlanName Edm.String R The 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

Name Type Read/Write Description
defaultPolicy Edm.String RW Reserved for internal use only. Do not use. Removed in version 1.5.
allowedPolicies Collection(Edm.String) RW Reserved 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

Name Type Read/Write Description
type Edm.String RW A string value that can be used to classify user sign-in types in your directory, such as "emailAddress" or "userName".
value Edm.String RW The 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

Name Type Read/Write Description
issuer Edm.String RW The string representation of the identity provider that issued the user identifier, such as facebook.com.
issuerUserId Edm.Binary RW The 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

Name Type Read/Write Description
capabilities Edm.String R For example, "Email", "OfficeCommunicationsOnline".
default Edm.Boolean R true if this is the default domain associated with the tenant; otherwise, false.
id Edm.String R For example, "00057FFE80187238".
initial Edm.Boolean R
name Edm.String R The domain name; for example, "contoso.onmicrosoft.com"
type Edm.String R For example, "Managed".

Additional Resources

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