Azure AD Graph API reference

The Azure Active Directory (AD) Graph API is an OData 3.0 compliant service that you can use to read and modify objects such as users, groups, and contacts in a tenant. Azure AD Graph API exposes REST endpoints that you send HTTP requests to in order to perform operations using the service. Use the Try It! experience to change the parameters of selected operations and observe the responses that are returned from the demo tenant.

A successful request to the Graph API must be addressed to a valid endpoint and be well-formatted, that is, it must contain any required headers and, if necessary, a JSON payload in the request body. The app making the request must include a token received from Azure AD that proves that it is authorized to access the resources targeted by the request. The app must be able to handle any responses received from the Graph API.

API Endpoint

https://graph.windows.net

Important

Azure AD Graph API functionality is also available through Microsoft Graph, a unified API that also includes APIs from other Microsoft services like Outlook, OneDrive, OneNote, Planner, and Office Graph, all accessed through a single endpoint with a single access token.

Every request to the Graph API must have a bearer token issued by Azure Active Directory attached. The token carries information about your app, the signed-in user (in the case of delegated permissions), authentication, and the operations on the directory that your app is authorized to perform. This token is carried in the Authorization header of the request. For example (the token has been shortened for brevity).

The Graph API performs authorization based on OAuth 2.0 permission scopes present in the token. For more information about the permission scopes that the Graph API exposes, see Graph API Permission Scopes.

In order for your app to authenticate with Azure AD and call the Graph API, you must add it to your tenant and configure it to require permissions (OAuth 2.0 permission scopes) for Windows Azure Active Directory. For information about adding and configuring an app, see Integrating Applications with Azure Active Directory.

Azure AD uses the OAuth 2.0 authentication protocol. You can learn more about OAuth 2.0 in Azure AD, including supported flows and access tokens in OAuth 2.0 in Azure AD.

Authorization Header

Authorization: Bearer eyJ0eX ... FWSXfwtQ

To perform operations with the Graph API, you send HTTP requests with a supported method - typically GET, POST, PATCH, PUT, or DELETE -- to an endpoint that targets the service, a resource collection, an individual resource, a navigation property of a resource, or a function or action exposed by the service. Endpoints are expressed as URLs.

The Graph API performs authorization based on OAuth 2.0 permission scopes present in the token. For more information about the permission scopes that the Graph API exposes, see Graph API Permission Scopes.

In order for your app to authenticate with Azure AD and call the Graph API, you must add it to your tenant and configure it to require permissions (OAuth 2.0 permission scopes) for Windows Azure Active Directory. For information about adding and configuring an app, see Integrating Applications with Azure Active Directory.

Azure AD uses the OAuth 2.0 authentication protocol. You can learn more about OAuth 2.0 in Azure AD, including supported flows and access tokens in OAuth 2.0 in Azure AD.

The following components comprise the URL:

Service Root: The service root for all Graph API requests is https://graph.windows.net.
Tenant Identifier {tenant_id}: The identifier for the tenant that the request targets.
Resource path {resource_path}: The path to the resource -- for example, a user or a group -- that the request targets.
Graph API Version {api_version}: The version of the Graph API targeted by the request. This is expressed as a query parameter and is required.

Basic format of a Graph API endpoint

https://graph.windows.net/{tenant_id}/{resource_path}?{api_version}

Note

In some cases, when reading resource collections, OData query parameters can be added to the request to filter, order, and page the result set. For more information, see the OData query parameters section in this topic.

By tenant object ID: The GUID that was assigned when the tenant was created. This can be found in the objectId property of the TenantDetail object.

Addressing the users resource collection by using the tenant object ID

https://graph.windows.net/12345678-9abc-def0-1234-56789abcde/users?api-version=1.6

By verified (registered) domain name: One of the domain names that are registered for the tenant. These can be found in the verifiedDomains property of the TenantDetail object.

Addressing the users resource collection of a tenant that has the domain contoso.com

https://graph.windows.net/contoso.com/users?api-version=1.6

By using the myOrganization alias: This alias is only available when using OAuth Authorization Code Grant type (3-legged) authentication; that is, when using a delegated permission scope. The alias is not case sensitive. It replaces the object ID or tenant domain in the URL. When the alias is used, Graph API derives the tenant from the claims presented in the token attached to the request.

Addressing the users resource collection of a tenant using this alias

https://graph.windows.net/myorganization/users?api-version=1.6

By using the me alias: This alias is only available when using OAuth Authorization Code Grant type (3-legged) authentication; that is, when using a delegated permission scope. The alias is not case sensitive. It replaces the object ID or tenant domain in the URL. When the alias is used, Graph API derives the user from the claims presented in the token attached to the request.

Note

You use me alias solely to target operations against the signed-in user. For more information, see Signed-in User Operations.

Addressing the signed-in user using the me alias

https://graph.windows.net/me?api-version=1.6

Returns the service metadata document.

Note

No authentication is necessary to read the service metadata.

Path

/$metadata

E.g. Targeting service metadata using the contoso.com tenant

https://graph.windows.net/contoso.com/$metadata?api-version=1.6

Targets a resource collection, such as users or groups in the tenant. You can use this path to read resources in the collection, and, depending on the resource type, to create a new resource in the tenant. In many cases the result set returned by a read can be further refined by the addition of query parameters to filter, order, or page the results.

Path

/{resource_collection}

E.g. Targetting the user collection

https://graph.windows.net/myorganization/users?api-version=1.6

Targets a specific resource in a tenant, such as a user, organizational contact, or group. For most resources the resource_id is the object ID. Some resources allow additional specifiers; for example, users can be also specified by user principal name (UPN). Depending on the resource, you can use this path to get the declared properties of the resource, to modify its declared properties, or to delete the resource.

Path

/{resource_collection}/{resource_id}

E.g. Targetting a specific user

https://graph.windows.net/contoso.com/users/[email protected]?api-version=1.6

Targets a navigation property of a specific resource, such as a user's manager or group memberships, or a group's members. You can use this path to return the object or objects referenced by the target navigation property.

Note

This form of addressing is only available for reads.

Path

/{resource_collection}/{resource_id}/{property_name}

E.g. Targetting the manager of [email protected]

https://graph.windows.net/contoso.com/users/[email protected]/manager?api-version=1.6

Targets a navigation property of a specific resource, such as a user's manager or group memberships, or a group's members. You can use this form of addressing to both read and modify a navigation property. On reads, the objects referenced by the property are returned as one or more links in the response body. On writes, the objects are specified as one or more links in the request body.

Path

/{resource_collection}/{resource_id}/$links/{property_name}

E.g. Targetting the manager property of [email protected]

https://graph.windows.net/contoso.com/users/[email protected]/$links/manager?api-version=1.6

Targets a function or action exposed at the tenant. Functions and actions are typically invoked with a POST Request and may include a request body.

Path

/{function_name}

E.g. Targetting the isMemberOf function

https://graph.windows.net/myorganization/isMemberOf?api-version=1.6

Targets a function or action exposed on a resource. Functions and actions are typically invoked with a POST Request and may include a request body.

Path

/{resource_collection}/{resource_id}/{function_name}

E.g. Targetting the getMemberGroups function/figcaption>

https://graph.windows.net/contoso.com/users/[email protected]?api-version=1.6

You use the api-version query parameter to target a specific version of the Graph API for an operation. This parameter is required.

The value for the api-version parameter can be one of the following:

"beta"
"1.6"
"1.5"
"2014/11/08"
"2-13/04/05"

E.g. Targetting the user collection using Graph API version 1.6

https://graph.windows.net/myorganization/users?api-version=1.6

In many cases when you read a collection of resources, you can filter, sort, and page the result set by attaching OData query parameters to your request.

The Graph API supports the following Odata query parameters:

$filter
$batch
$expand
$orderby
$top
$skiptoken and previous-page

See Supported Queries, Filters, and Paging Options for more information about supported OData query parameters and their limitations in the Graph API.

The adjoining table shows common HTTP headers used in requests with the Graph API. It is not meant to be comprehensive.

At a minimum, we recommend you do the following for each request:

Log an accurate time stamp of the request submission.
Send and log the client-request-id.
Log the HTTP response code and request-id.

Providing information in such logs will help Microsoft troubleshoot issues when you ask for help or support.

Request Headers
Header	Description
Authorization	Required. A bearer token issued by Azure Active Directory. See Authentication and Authorization in this topic for more information.
Content-Type	Required if request body is present. The media type of the content in the request body. Use application/json. Parameters may be included with the media type. Note: application/atom+xml and application/xml (for links) are supported but are not recommended both for performance reasons and because support for XML will be deprecated in a future release.
Content-Length	Required if request body is present. The length of the request in bytes.

The adjoining table shows common HTTP headers returned in responses by the Graph API. It is not meant to be comprehensive.

Response Headers
Header	Description
Content-Type	The media type of the content in the response body. The default is application/json. Requests for user thumbnail photos return image/jpeg by default.
Location	Returned in responses to POST requests that create a new resource (object) in the directory. Contains the URI of the newly created resource.
ocp-aad-diagnostics-server-name	The identifier for the server that performed the requested operation.
ocp-aad-session-key	The key that identifies the current session with the directory service.

Request bodies for POST, PATCH, and PUT requests can be sent in JSON or XML payloads. Server responses can be returned in JSON or XML payloads. You can specify the payload in request bodies by using the Content-Type request header and in responses by using the Accept request header.

Important

We strongly recommend that you use JSON payloads in requests and responses with the Graph API. This is both for performance reasons and because XML will be deprecated in a future release.

The preceding sections discussed the formatting of basic requests and responses with the Graph API. More advanced features may add additional query string parameters or have significantly different request and response bodies than the basic operations discussed previously in this topic.

These features include:

Batch Processing: The Graph API supports batching. Sending requests in batches reduces round trips to the server, which reduces network overhead and helps your operations complete more quickly. For more information about batch processing with the Graph API, see Batch Processing.
Differential Query: The Graph API supports performing differential queries. Differential query allows you to return changes to specific entities in a tenant between requests issued at different times. This feature is often used to sync a local store with changes on the tenant. For more information about differential query with the Graph API, see Differential Query.

Overview

With the Azure AD Graph API, you can create, read, update, and delete users. You can also query and modify a user's relationships to other directory entities. For example, you can assign the user's manager, query the user's direct reports, manage group memberships, app roles, and devices assigned to the user, and much more.

You specify the resource path differently depending on whether you are targeting the collection of all users in your tenant, an individual user, or a navigation property of a specific user.

You can use this resource path to read all users or a filtered list of users in your tenant or to create one or more new users in your tenant.

Targets a user resource collection

/users

You specify the user_id either as the object ID (GUID) or the user principal name (UPN) of the target user. You can use this resource path to get the declared properties of a user, to modify the declared properties of a user, or to delete a user.

Targets an individual user in your tenant

/users/{user_id}

You can use it to return the object or objects referenced by the target navigation property of the specified user. Note: This form of addressing is only available for reads.

Targets a specified navigation property of a user

/users/{user_id}/{property}

You can use this form of addressing to both read and modify a navigation property. On reads, the objects referenced by the property are returned as one or more links in the response body. On writes, the objects are specified as one or more links in the request body.

Also targets a specified navigation property of a user

/users/{user_id}/$links/{property}

Properties

1. accountEnabled
2. Edm.Boolean
true if the account is enabled; otherwise, false. This property is required when a user is created.
1. C
2. R
3. U
4. D
5. Filterable
1. assignedLicenses
2. Collection(AssignedLicense)
The licenses that are assigned to the user. Not nullable.
1. C
2. R
3. U
4. D
1. assignedPlans
2. Edm.String
The plans that are assigned to the user.
1. C
2. R
3. U
4. D
1. deletionTimeStamp
2. Edm.DateTime
This property is not valid for users and always returns null. Inherited from DirectoryObject. Requires version 1.5 or newer.
1. C
2. R
3. U
4. D
1. department
2. Edm.String
The name for the department in which the user works.
1. C
2. R
3. U
4. D
5. Filterable
1. dirSyncEnabled
2. Edm.Boolean
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).
1. displayName
2. Edm.String
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.
1. facsimileTelephoneNumber
2. Edm.String
The telephone number of the user's business fax machine.
1. givenName
2. Edm.String
The given name (first name) of the user.
1. immutableId
2. Edm.String
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. The $ and _ characters cannot be used when specifying this property. Requires version 2013-11-08 or newer.
1. jobTitle
2. Edm.String
The user’s job title.
1. lastDirSyncTime
2. Edm.DateTime
Indicates the last time at which the object was synced with the on-premises directory; for example: "2013-02-16T03:04:54Z"
1. Email
2. Edm.String
The SMTP address for the user, for example, "[email protected]".
1. mailNickname
2. Edm.String
The mail alias for the user. This property must be specified when a user is created.
1. mobile
2. Edm.String
The primary cellular telephone number for the user.
1. objectId
2. Edm.Guid
The unique identifier for the user. Inherited from DirectoryObject. Key, immutable, not nullable, unique.
1. objectType
2. Edm.String
A string that identifies the object type. For users the value is always “User”. Inherited from DirectoryObject.
1. onPremisesSecurityIdentifier
2. Edm.String
Contains the on-premises security identifier (SID) for the user that was synchronized from on-premises to the cloud. Requires version 1.5 or newer.
1. otherMails
2. Edm.String
A list of additional email addresses for the user; for example: ["[email protected]", "[email protected]"]. Not nullable, the any operator is required for filter expressions on multi-valued properties; for more information, see Supported Queries, Filters, and Paging Options.
1. passwordPolicies
2. Edm.String
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".
1. passwordProfile
2. PasswordProfile
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.
1. physicalDeliveryOfficeName
2. Edm.String
The office location in the user's place of business.
1. postalCode
2. Edm.String
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.
1. preferredLanguage
2. Edm.String
The preferred language for the user. Should follow ISO 639-1 Code; for example "en-US".
1. provisionedPlans
2. Collection(ProvisionedPlan)
The plans that are provisioned for the user. Not nullable.
1. provisioningErrors
2. Collection(ProvisioningError)
A collection of error details that are preventing this user from being provisioned successfully.
1. proxyAddresses
2. Collection(Edm.String)
For example: ["SMTP: [email protected]", "smtp: [email protected]"]. 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.
1. sipProxyAddress
2. Edm.String
Specifies the voice over IP (VOIP) session initiation protocol (SIP) address for the user. Requires version 1.5 or newer.
1. givenName
2. Edm.String
The given name (first name) of the user.
1. givenName
2. Edm.String
The state or province in the user's address.
1. streetAddress
2. Edm.String
The street address of the user's place of business.
1. surname
2. Edm.String
The user's surname (family name or last name). Filterable.
1. surname
2. Edm.String
The primary telephone number of the user's place of business.
1. thumbnailPhoto
2. Edm.Stream
A thumbnail photo to be displayed for the user. Not nullable.
1. usageLocation
2. Edm.String
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". Not nullable.
1. userPrincipalName
2. Edm.String
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, where domain must be present in the tenant’s collection of verified domains. This property is required when a user is created.
1. userType
2. Edm.String
A string value that can be used to classify user types in your directory, such as “Member” and “Guest”. Requires version 2013-11-08 or newer.

Sample JSON Response

{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#directoryObjects/Microsoft.DirectoryServices.User/@Element",
  "odata.type": "Microsoft.DirectoryServices.User",
  "objectType": "User",
  "objectId": "13addec1-c5ae-47f5-a1fe-202be14b1570",
  "deletionTimestamp": null,
  "accountEnabled": true,
  "assignedLicenses": [
    {
      "disabledPlans": [],
      "skuId": "6fd2c87f-b296-42f0-b197-1e91e994b900"
    }
  ],
  "assignedPlans": [
    {
      "assignedTimestamp": "2014-10-14T02:54:04Z",
      "capabilityStatus": "Enabled",
      "service": "exchange",
      "servicePlanId": "efb87545-963c-4e0d-99df-69c6916d9eb0"
    },
    {
      "assignedTimestamp": "2014-10-14T02:54:04Z",
      "capabilityStatus": "Enabled",
      "service": "SharePoint",
      "servicePlanId": "5dbe027f-2339-4123-9542-606e4d348a72"
    },
    {
      "assignedTimestamp": "2014-10-14T02:54:04Z",
      "capabilityStatus": "Enabled",
      "service": "SharePoint",
      "servicePlanId": "e95bec33-7c88-4a70-8e19-b10bd9d0c014"
    },
    {
      "assignedTimestamp": "2014-10-14T02:54:04Z",
      "capabilityStatus": "Enabled",
      "service": "MicrosoftCommunicationsOnline",
      "servicePlanId": "0feaeb32-d00e-4d66-bd5a-43b5b83db82c"
    },
    {
      "assignedTimestamp": "2014-10-14T02:54:04Z",
      "capabilityStatus": "Enabled",
      "service": "MicrosoftOffice",
      "servicePlanId": "43de0ff5-c92c-492b-9116-175376d08c38"
    },
    {
      "assignedTimestamp": "2014-10-14T02:54:04Z",
      "capabilityStatus": "Enabled",
      "service": "RMSOnline",
      "servicePlanId": "bea4c11e-220a-4e6d-8eb8-8ea15d019f90"
    }
  ],
  "city": "Tulsa",
  "country": "United States",
  "department": "Sales & Marketing",
  "dirSyncEnabled": null,
  "displayName": "Garth Fort",
  "facsimileTelephoneNumber": null,
  "givenName": "Garth",
  "immutableId": null,
  "jobTitle": "Web Marketing Manager",
  "lastDirSyncTime": null,
  "mail": "[email protected]",
  "mailNickname": "garthf",
  "mobile": null,
  "onPremisesSecurityIdentifier": null,
  "otherMails": [],
  "passwordPolicies": "None",
  "passwordProfile": null,
  "physicalDeliveryOfficeName": "20/1101",
  "postalCode": "74133",
  "preferredLanguage": "en-US",
  "provisionedPlans": [
    {
      "capabilityStatus": "Enabled",
      "provisioningStatus": "Success",
      "service": "exchange"
    },
    {
      "capabilityStatus": "Enabled",
      "provisioningStatus": "Success",
      "service": "MicrosoftCommunicationsOnline"
    },
    {
      "capabilityStatus": "Enabled",
      "provisioningStatus": "Success",
      "service": "SharePoint"
    },
    {
      "capabilityStatus": "Enabled",
      "provisioningStatus": "Success",
      "service": "SharePoint"
    },
    {
      "capabilityStatus": "Enabled",
      "provisioningStatus": "Success",
      "service": "MicrosoftOffice"
    }
  ],
  "provisioningErrors": [],
  "proxyAddresses": [
    "SMTP:[email protected]"
  ],
  "sipProxyAddress": "[email protected]",
  "state": "OK",
  "streetAddress": "7633 E. 63rd Place, Suite 300",
  "surname": "Fort",
  "telephoneNumber": "+1 918 555 0101",
  "usageLocation": "US",
  "userPrincipalName": "[email protected]",
  "userType": "Member"
}

Properties

1. accountEnabled
2. boolean
true if the account is enabled; otherwise, false.
1. displayName
2. string
The name to display in the address book for the user.
1. immutableId
2. string
Only needs to be specified when creating a new user account if you are using a federated domain for the user's userPrincipalName (UPN) property.
1. mailNickname
2. string
The mail alias for the user.
1. passwordProfile
2. PasswordProfile
The password profile for the user.
1. userPrincipalName
2. string
The user principal name ([email protected]).

Returns

On success, returns the newly created User; otherwise, the response body contains error details. For more information about errors, see Error Codes and Error Handling.

HTTP Response Codes

1. 201
Created. Indicates success. The new user is returned in the response body.

Request

POST https://graph.windows.net/myorganization/users?api-version

Request Body

{
  "accountEnabled": true,
  "displayName": "Alex Wu",
  "mailNickname": "AlexW",
  "passwordProfile": {
    "password": "Test1234",
    "forceChangePasswordNextLogin": false
  },
  "userPrincipalName": "[email protected]"
}

Response Body

{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#directoryObjects/Microsoft.DirectoryServices.User/@Element",
  "odata.type": "Microsoft.DirectoryServices.User",
  "objectType": "User",
  "objectId": "84fba1e8-b942-47c9-a10e-a4bee353ce60",
  "deletionTimestamp": null,
  "accountEnabled": true,
  "assignedLicenses": [],
  "assignedPlans": [],
  "city": null,
  "country": null,
  "department": null,
  "dirSyncEnabled": null,
  "displayName": "Alex Wu",
  "facsimileTelephoneNumber": null,
  "givenName": null,
  "immutableId": null,
  "jobTitle": null,
  "lastDirSyncTime": null,
  "mail": null,
  "mailNickname": "AlexW",
  "mobile": null,
  "onPremisesSecurityIdentifier": null,
  "otherMails": [],
  "passwordPolicies": null,
  "passwordProfile": null,
  "physicalDeliveryOfficeName": null,
  "postalCode": null,
  "preferredLanguage": null,
  "provisionedPlans": [],
  "provisioningErrors": [],
  "proxyAddresses": [],
  "sipProxyAddress": null,
  "state": null,
  "streetAddress": null,
  "surname": null,
  "telephoneNumber": null,
  "usageLocation": null,
  "userPrincipalName": "[email protected]",
  "userType": "Member"
}

Properties

1. user_id
2. string
The user ID. Can be the object ID (GUID) or the user principal name ([email protected]) of the target user.
1. api-version
2. string
Specifies the version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required.

Returns

On success, returns the User object for the specified user; otherwise, the response body contains error details. For more information about errors, see Error Codes and Error Handling.

HTTP Response Codes

1. 200
OK. Indicates success. The user is returned in the response body.

Request

GET https://graph.windows.net/myorganization/users/{user_id}?api-version

Example Response Body

{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#directoryObjects/Microsoft.DirectoryServices.User/@Element",
  "odata.type": "Microsoft.DirectoryServices.User",
  "objectType": "User",
  "objectId": "13addec1-c5ae-47f5-a1fe-202be14b1570",
  "deletionTimestamp": null,
  "accountEnabled": true,
  "assignedLicenses": [
    {
      "disabledPlans": [],
      "skuId": "6fd2c87f-b296-42f0-b197-1e91e994b900"
    }
  ],
  "assignedPlans": [
    {
      "assignedTimestamp": "2014-10-14T02:54:04Z",
      "capabilityStatus": "Enabled",
      "service": "exchange",
      "servicePlanId": "efb87545-963c-4e0d-99df-69c6916d9eb0"
    },
    {
      "assignedTimestamp": "2014-10-14T02:54:04Z",
      "capabilityStatus": "Enabled",
      "service": "SharePoint",
      "servicePlanId": "5dbe027f-2339-4123-9542-606e4d348a72"
    },
    {
      "assignedTimestamp": "2014-10-14T02:54:04Z",
      "capabilityStatus": "Enabled",
      "service": "SharePoint",
      "servicePlanId": "e95bec33-7c88-4a70-8e19-b10bd9d0c014"
    },
    {
      "assignedTimestamp": "2014-10-14T02:54:04Z",
      "capabilityStatus": "Enabled",
      "service": "MicrosoftCommunicationsOnline",
      "servicePlanId": "0feaeb32-d00e-4d66-bd5a-43b5b83db82c"
    },
    {
      "assignedTimestamp": "2014-10-14T02:54:04Z",
      "capabilityStatus": "Enabled",
      "service": "MicrosoftOffice",
      "servicePlanId": "43de0ff5-c92c-492b-9116-175376d08c38"
    },
    {
      "assignedTimestamp": "2014-10-14T02:54:04Z",
      "capabilityStatus": "Enabled",
      "service": "RMSOnline",
      "servicePlanId": "bea4c11e-220a-4e6d-8eb8-8ea15d019f90"
    }
  ],
  "city": "Tulsa",
  "country": "United States",
  "department": "Sales & Marketing",
  "dirSyncEnabled": null,
  "displayName": "Garth Fort",
  "facsimileTelephoneNumber": null,
  "givenName": "Garth",
  "immutableId": null,
  "jobTitle": "Web Marketing Manager",
  "lastDirSyncTime": null,
  "mail": "[email protected]",
  "mailNickname": "garthf",
  "mobile": null,
  "onPremisesSecurityIdentifier": null,
  "otherMails": [],
  "passwordPolicies": "None",
  "passwordProfile": null,
  "physicalDeliveryOfficeName": "20/1101",
  "postalCode": "74133",
  "preferredLanguage": "en-US",
  "provisionedPlans": [
    {
      "capabilityStatus": "Enabled",
      "provisioningStatus": "Success",
      "service": "exchange"
    },
    {
      "capabilityStatus": "Enabled",
      "provisioningStatus": "Success",
      "service": "MicrosoftCommunicationsOnline"
    },
    {
      "capabilityStatus": "Enabled",
      "provisioningStatus": "Success",
      "service": "SharePoint"
    },
    {
      "capabilityStatus": "Enabled",
      "provisioningStatus": "Success",
      "service": "SharePoint"
    },
    {
      "capabilityStatus": "Enabled",
      "provisioningStatus": "Success",
      "service": "MicrosoftOffice"
    }
  ],
  "provisioningErrors": [],
  "proxyAddresses": [
    "SMTP:[email protected]"
  ],
  "sipProxyAddress": "[email protected]",
  "state": "OK",
  "streetAddress": "7633 E. 63rd Place, Suite 300",
  "surname": "Fort",
  "telephoneNumber": "+1 918 555 0101",
  "usageLocation": "US",
  "userPrincipalName": "[email protected]",
  "userType": "Member"
}

Properties

In the request body, any writable property in the User Entity can be specified.

1. user_id
2. string
The user ID. Can be the object ID (GUID) or the user principal name ([email protected]) of the target user.
1. api-version
2. string
Specifies the version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required.

Returns

On success, no response body is returned; otherwise, the response body contains error details. For more information about errors, see Error Codes and Error Handling.

HTTP Response Codes

1. 204
No Content. Indicates success. No response body is returned.

Request

PATCH https://graph.windows.net/myorganization/users/{user_id}?api-version

Example request body that resets a user's password

{
  "passwordProfile": {
    "password": "Test123456",
    "forceChangePasswordNextLogin": false
  }
}

You use can use the me alias to target the signed-in user. This alias replaces the {tenant id} and {resource path} segments in the request URL. When you send a request to the Graph API with the me alias, it derives the tenant and user from the bearer token attached to the request.

Endpoint

https://graph.windows.net/me?api-version=1.6

You specify the URL differently depending on whether you are targeting the signed-in user or one of its navigation properties.

me targets the signed-in user. You can use this resource path to get the declared properties of the user and to modify the declared properties of the user.
me/{nav_property} targets the specified navigation property of the signed-in user. You can use it to return the object or objects referenced by the target navigation property of the user.

Note

This form of addressing is only available for reads.
me/$links/{nav_property} targets the specified navigation property of the signed-in user. You can use this form of addressing to both read and modify a navigation property. On reads, the objects referenced by the property are returned as one or more links in the response body. On writes, the objects are specified as one or more links in the request body.

Gets the signed-in user

GET https://graph.windows.net/me?api-version

Updates properties of the signed-in user (writable User properties specified in the body)

PATCH https://graph.windows.net/me[?api-version]

Gets the signed-in user's manager

GET https://graph.windows.net/me/manager?api-version

Gets a link to the signed-in user's manager

GET https://graph.windows.net/me/$links/manager?api-version=1.6

Assigns the signed-in user's manager (link to the User/Contact to assign specified in the body)

PUT https://graph.windows.net/me/$links/manager?api-version

Properties

1. identityProvider
2. Edm.String
The user ID. Can be the object ID (GUID) or the user principal name ([email protected]) of the target user.
1. key
2. Edm.Binary
Specifies the version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required.
1. type
2. Edm.Int32
Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required.

Sample JSON

{
  "identityProvider": "Lorem_ipsum_dolor_sit",
  "key": "213421-214fgs32-gds532432-dsvcsg-532532",
  "type": "2134214213421"
}

Properties

1. allowedMemberTypes
2. Collection(Edm.String)
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. Not nullable.
1. description
2. Edm.String
Permission help text that appears in the admin app assignment and consent experiences.
1. displayName
2. Edm.String
Display name for the permission that appears in the admin consent and app assignment experiences.
1. id
2. Edm.Guid
Unique role identifier inside the appRoles collection.
1. isEnabled
2. Edm.Boolean
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.
1. value
2. Edm.String
Specifies the value of the roles claim that the application should expect in the authentication and access tokens.

Sample JSON

{
  "allowedMemberTypes": "User",
  "description": "Lorem ipsum dolor sit amet, nec ad quot soleat, alia blandit an per. Ne oratio prompta qui.",
  "displayName": "Marketing",
  "id": "2134214213421",
  "isEnabled": "true",
  "value": "213421-214fgs32-gds532432-dsvcsg-532532"
}