Functions and actions | Graph API reference

Applies to: Graph API | Azure Active Directory

This topic discusses the functions and actions that are exposed by Azure AD Graph API and how you can call them.

The Azure AD 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 directoryObject resource type.

Using the Graph API to call actions and functions

To call an action or a function with the Graph API, you send POST requests to the appropriate endpoint.

Graph API requests use the following basic URL:

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

Functions or actions that are called on the directory service itself do not require a resource path. For functions or operations that are called on a specific resource, you will specify the {resource_path} differently depending on the resource that you are targeting. The resource path will have the following parts:

• (resource_collection} specifies the resource collection, such as users, contacts, or groups.
• {resource_id} identifies the specific resource to target in the resource collection. Typically an object ID (GUID), but, in the case of a user, you can also use the user principal name (UPN).

You can use the me alias to target the signed-in user. This alias replaces the following URL path segments: {tenant_id}/users/{user_id}. When you use this alias, the Graph API gets the user and tenant from the bearer token attached to the request.

For example, the following POST request can be used to assign a license to the signed-in user (you must also include an appropriate request body) :

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

For more information about performing operations using the me alias, see REST operations on the signed-in user.

Functions

Functions have no side effects in the directory. That is, when you call a function, it only returns data, it does not modify any data in the directory. The following topics show you how to call functions with the Graph API.

applications: Get application properties by object ID

Call the applications function specifying the objectID to return the details of an application.

Important: Requires version 1.6 or newer.

GET https://graph.windows.net/myorganization/applications/{application_oid}?api-version

Parameters

GET https://graph.windows.net/myorganization/applications/00009987-f6d8-4957-a6ca-7848d986ffff?api-version=1.6

Response

Status Code:200

Content-Type: application/json

{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#Collection(Microsoft.DirectoryServices.directoryObjects/@Element)",
  "odata.type": "Microsoft.DirectoryServices.Application",
  "objectType": "Application",
  "objectId": "35418b3b-476c-4271-81a8-6db65d397ff4",
  "deletionTimestamp": null,
  "addIns": [],
  "allowActAsForAllClients": null,
  "appBranding": null,
  "appCategory": null,
  "appData": null,
  "appId": "1062a13d-f7e5-4ea7-8d24-427f6ff1e5e1",
  "appMetadata": {
    "version": 0,
    "data": [
      {
        "key": "ApplicationMetadata",
        "value": "eyJBcHBsaWNhd..."
      }
    ]
  },
  "appRoles": [],
  "availableToOtherTenants": true,
  "displayName": "Test App",
  "encryptedMsiApplicationSecret": null,
  "errorUrl": null,
  "groupMembershipClaims": "None",
  "homepage": null,
  "identifierUris": [],
  "keyCredentials": [
    {
      "customKeyIdentifier": "pZMUkCG+igju29A1o/BYhnWffff=",
      "endDate": "2017-10-11T07:00:00Z",
      "keyId": "dceb697c-477a-4a25-be87-38282995ffff",
      "startDate": "2012-09-11T07:00:00Z",
      "type": "AsymmetricX509Cert",
      "usage": "Verify",
      "value": null
    },
    {
      "customKeyIdentifier": "pEFcLQgJrxgCgQwBbtV/G5Cffff=",
      "endDate": "2017-06-19T07:00:00Z",
      "keyId": "fed7d654-4ae7-4a53-bd60-71dc7eb0ffff",
      "startDate": "2012-05-19T07:00:00Z",
      "type": "AsymmetricX509Cert",
      "usage": "Verify",
      "value": null
    }
  ],
  "knownClientApplications": [],
  "logoUrl": null,
  "logoutUrl": null,
  "oauth2AllowImplicitFlow": false,
  "oauth2AllowUrlPathMatching": false,
  "oauth2Permissions": [],
  "oauth2RequirePostResponse": false,
  "passwordCredentials": [],
  "publicClient": false,
  "recordConsentConditions": null,
  "replyUrls": [],
  "requiredResourceAccess": [],
  "samlMetadataUrl": null,
  "supportsConvergence": false,
  "tokenEncryptionKeyId": null
}

Response List

Request Body None.

Response Body

applicationsByAppId: Get application properties by application ID

Call the applicationsByAppId function specifying the appID to return details of an application.

Important: Requires version 1.6 or newer.

GET https://graph.windows.net/myorganization/applicationsByAppId/{application_id}?api-version

Parameters

GET https://graph.windows.net/myorganization/applicationsByAppId/1062a13d-f7e5-4ea7-8d24-427f6ff1e5e1?api-version=1.6

Response

Status Code:200

Content-Type: application/json

{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#directoryObjects/Microsoft.DirectoryServices.Application/@Element",
  "odata.type": "Microsoft.DirectoryServices.Application",
  "objectType": "Application",
  "objectId": "35418b3b-476c-4271-81a8-6db65d397ff4",
  "deletionTimestamp": null,
  "addIns": [],
  "allowActAsForAllClients": null,
  "appBranding": null,
  "appCategory": null,
  "appData": null,
  "appId": "1062a13d-f7e5-4ea7-8d24-427f6ff1e5e1",
  "appMetadata": {
    "version": 0,
    "data": [
      {
        "key": "ApplicationMetadata",
        "value": "eyJBcHBsaWNhd..."
      }
    ]
  },
  "appRoles": [],
  "availableToOtherTenants": true,
  "displayName": "Test App",
  "encryptedMsiApplicationSecret": null,
  "errorUrl": null,
  "groupMembershipClaims": "None",
  "homepage": null,
  "identifierUris": [],
  "keyCredentials": [
    {
      "customKeyIdentifier": "pZMUkCG+igju29A1o/BYhnWffff=",
      "endDate": "2017-10-11T07:00:00Z",
      "keyId": "dceb697c-477a-4a25-be87-38282995ffff",
      "startDate": "2012-09-11T07:00:00Z",
      "type": "AsymmetricX509Cert",
      "usage": "Verify",
      "value": null
    },
    {
      "customKeyIdentifier": "pEFcLQgJrxgCgQwBbtV/G5Cffff=",
      "endDate": "2017-06-19T07:00:00Z",
      "keyId": "fed7d654-4ae7-4a53-bd60-71dc7eb0ffff",
      "startDate": "2012-05-19T07:00:00Z",
      "type": "AsymmetricX509Cert",
      "usage": "Verify",
      "value": null
    }
  ],
  "knownClientApplications": [],
  "logoUrl": null,
  "logoutUrl": null,
  "oauth2AllowImplicitFlow": false,
  "oauth2AllowUrlPathMatching": false,
  "oauth2Permissions": [],
  "oauth2RequirePostResponse": false,
  "passwordCredentials": [],
  "publicClient": false,
  "recordConsentConditions": null,
  "replyUrls": [],
  "requiredResourceAccess": [],
  "samlMetadataUrl": null,
  "supportsConvergence": false,
  "tokenEncryptionKeyId": null
}

Response List

Request Body None.

Response Body

checkMemberGroups: Check for membership in a list of groups

Call checkMemberGroups to check the membership of a user, contact, group, or service principal in a list of groups. The operation is transitive.

You can check up to a maximum of 20 groups per request.

POST https://graph.windows.net/myorganization/{resource_collection}/{resource_id}/checkMemberGroups?api-version

Parameters

{
  "groupIds": [
    "8ab3f116-1afb-44cb-8e61-6b20cb1e353c",
    "be78b7e2-a94a-4ab0-9bb4-403977cc7ec6",
    "cf61b8c9-3626-4fe4-b2f7-ac31fa905605"
  ]
}

POST https://graph.windows.net/myorganization/users/alexd%40a830edad9050849NDA1.onmicrosoft.com/checkMemberGroups?api-version=1.6

Response

Status Code:200

Content-Type: application/json

{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#Collection(Edm.String)",
  "value": [
    "8ab3f116-1afb-44cb-8e61-6b20cb1e353c",
    "be78b7e2-a94a-4ab0-9bb4-403977cc7ec6"
  ]
}

Response List

Request Body

Response Body

getAvailableExtensionProperties: Get the registered extension properties in a directory

Call the getAvailableExtensionProperties function to return all or a filtered list of the extension properties that have been registered in a directory. The following entities support extension properties: User, Group, TenantDetail, Device, Application, and ServicePrincipal. To learn more about how extension properties are registered and unregistered in a directory and how you can modify their values, see Directory Schema Extensions.

Important: Requires version 1.5 or newer.

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

Parameters

{
  "isSyncedFromOnPremises": false
}

Response

Status Code:200

Content-Type: application/json

{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#directoryObjects",
  "value": [
    {
      "odata.type": "Microsoft.DirectoryServices.ExtensionProperty",
      "objectType": "ExtensionProperty",
      "objectId": "d6a8bfec-893d-46e4-88fd-7db5fcc0fa62",
      "deletionTimestamp": null,
      "appDisplayName": "SampleApp",
      "name": "extension_4d405aa8baa04fb494d3e0571fd9fd71_skypeId",
      "dataType": "String",
      "isSyncedFromOnPremises": false,
      "targetObjects": [
        "User"
      ]
    }
  ]
}

Response List

Request Body

Response Body

getMemberGroups: Get group memberships (transitive)

Call the getMemberGroups function on a user, contact, group, or service principal to get the groups that it is a member of. The function is transitive.

Note: The maximum number of groups that can be returned is 2046. If the target object has direct or transitive membership in more than 2046 groups, the function returns an HTTP error response with an error code of Directory_ResultSizeLimitExceeded.

POST https://graph.windows.net/myorganization/{resource_collection}/{resource_id}/getMemberGroups?api-version

Parameters

{
  "securityEnabledOnly": false
}

POST  https://graph.windows.net/myorganization/users/alexd%40a830edad9050849NDA1.onmicrosoft.com/getMemberGroups?api-version=1.6

Response

Status Code:200

Content-Type: application/json

{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#Collection(Edm.String)",
  "value": [
    "8ab3f116-1afb-44cb-8e61-6b20cb1e353c",
    "be78b7e2-a94a-4ab0-9bb4-403977cc7ec6",
    "5e624f44-d38d-4943-b07c-2bad078f52ff"
  ]
}

Response List

Request Body

Response Body

getMemberObjects: Get group and directory role memberships (transitive)

Call the getMemberObjects function on a user, contact, group, or service principal to get the groups and directory roles that it is a member of. The function is transitive.

Note: The maximum number of groups and directory roles that can be returned is 2046. If the target object has direct or transitive membership in more than 2046 groups and directory roles, the function returns an HTTP error response with an error code of Directory_ResultSizeLimitExceeded.

Important: Requires version 1.5 or newer.

POST https://graph.windows.net/myorganization/{resource_collection}/{resource_id}/getMemberObjects?api-version

Parameters

{
  "securityEnabledOnly": false
}

POST https://graph.windows.net/myorganization/users/alexd%40a830edad9050849NDA1.onmicrosoft.com/getMemberObjects?api-version=1.6

Response

Status Code:200

Content-Type: application/json

{
  "odata.metadata": "https://graph.windows.net/myortanization/$metadata#Collection(Edm.String)",
  "value": [
    "8ab3f116-1afb-44cb-8e61-6b20cb1e353c",
    "be78b7e2-a94a-4ab0-9bb4-403977cc7ec6",
    "5e624f44-d38d-4943-b07c-2bad078f52ff"
  ]
}

Response List

Request Body

Response Body

getObjectsByObjectIds: Get objects from a list of object IDs

Call the getObjectsByObjectIds function on the directory service to return the directory objects specified in a list of object IDs. You can also specify which resource collections (users, groups, etc.) should be searched by specifying the optional types parameter.

Some common uses for this function are to:

• Resolve the object IDs returned by functions that return collections of object IDs such as getMemberObjects or getMemberGroups to their backing directory objects.
• Resolve object IDs persisted in an external store by the application to their backing directory objects.

Important: Requires version 1.5 or newer.

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

Parameters

{
  "objectIds": [
    "c57cdc98-0dcd-4f90-a82f-c911b288bab9",
    "cc9869f0-6ac0-4d00-bc24-621a2d949d35",
    "477c2fe9-b0e7-4661-8564-ba170666f058",
    "beb9a3bb-2fff-4d5f-99d8-0ce169e8bed7"
  ],
  "types": [
    "group"
  ]
}

Response

Status Code:200

Content-Type: application/json

{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#directoryObjects",
  "value": [
    {
      "odata.type": "Microsoft.DirectoryServices.Group",
      "objectType": "Group",
      "objectId": "c57cdc98-0dcd-4f90-a82f-c911b288bab9",
      "deletionTimestamp": null,
      "description": "Marketing Group",
      "dirSyncEnabled": null,
      "displayName": "Marketing",
      "lastDirSyncTime": null,
      "mail": null,
      "mailNickname": "cdf76b17-0734-41bc-9c24-9a7af93f3502",
      "mailEnabled": false,
      "onPremisesSecurityIdentifier": null,
      "provisioningErrors": [],
      "proxyAddresses": [],
      "securityEnabled": true
    },
    {
      "odata.type": "Microsoft.DirectoryServices.Group",
      "objectType": "Group",
      "objectId": "cc9869f0-6ac0-4d00-bc24-621a2d949d35",
      "deletionTimestamp": null,
      "description": "Engineering Group",
      "dirSyncEnabled": null,
      "displayName": "Engineering",
      "lastDirSyncTime": null,
      "mail": null,
      "mailNickname": "ef3b8cc1-721b-4452-9e30-9867d1de80ea",
      "mailEnabled": false,
      "onPremisesSecurityIdentifier": null,
      "provisioningErrors": [],
      "proxyAddresses": [],
      "securityEnabled": true
    }
  ]
}

Response List

Request Body

Response Body

isMemberOf: Check membership in a specific group (transitive)

Call the isMemberOf function on the directory service to check whether a specified user, group, contact, or service principal is a member of a specified group. The operation is transitive,

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

Parameters

{
  "groupId": "5e624f44-d38d-4943-b07c-2bad078f52ff",
  "memberId": "ea59e4d3-a7a1-4b5b-b65f-a25fcc0c0f99"
}

Response

Status Code:200

Content-Type: application/json

{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#Edm.Boolean",
  "value": true
}

Response List

Request Body

Response Body

servicePrincipalsByAppId: Get service principal object ID by application ID

Call the servicePrincipalsByAppId function on the directory service to return the the object ID of the specified application ID.

Important: Requires version 1.6 or newer.

GET https://graph.windows.net/myorganization/servicePrincipalsByAppId/{application_id}/objectId?api-version

Parameters

GET https://graph.windows.net/myorganization/servicePrincipalsByAppId/1062a13d-f7e5-4ea7-8d24-427f6ff1e5e1/objectId?api-version=1.6

Response

Status Code:200

Content-Type: application/json

{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#Edm.String",
  "value": [
    "00b4e797-7017-4720-b187-b01981c820d6"
  ]
}

Response List

Request Body

None.

Response Body

verify: Verify ownership of a domain

Call the verify action on a domain to validate the ownership of the domain.

Important: Only applies to an unverified domain (the isVerified property of the [Domain] is false). Only supported in version beta.

POST https://graph.windows.net/myorganization/domains({domain_name})/verify?api-version

Parameters

POST https://graph.windows.net/myorganization/domains(contoso.com)/verify?api-version=1.6

Response

Status Code:200

Content-Type: application/json

{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#domains/@Element",
  "authenticationType": "Managed",
  "availabilityStatus": "AvailableImmediately",
  "isAdminManaged": true,
  "isDefault": false,
  "isInitial": false,
  "isRoot": true,
  "isVerified": true,
  "name": "contoso.com",
  "supportedServices": []
}

Response List

Request Body

None.

Response Body

Actions

Actions have side effects in the directory. That is, when you call an action, it may alter data in the directory. For example, it may assign a license to a user or restore an application that has previously been deleted.

addKey: Add a KeyCredential for an application

Call the addKey action to add a KeyCredential for an application.

Important: Requires version v1.6 or newer

POST https://graph.windows.net/myorganization/applications/{application_oid}/addKey?api-version

Parameters

{
  "keyCredential": {
    "customKeyIdentifier": "6uv7gh",
    "endDate": "endDate=2017-10-11T07:00:00Z",
    "keyId": "633b1614-b669-47c5-961e-f4a45978ffff",
    "type": "AsymmetricX509Cert",
    "usage": "Verify",
    "value": null
  },
  "passwordCredential": null,
  "proof": "Bearer eyJ0eXAiOiJKv1..."
}

POST 
https://graph.windows.net/myorganization/applications/00009987-f6d8-4957-a6ca-7848d986ffff/addKey?api-version=1.6

Response

Status Code:200

Content-Type: application/json

{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#Collection(Microsoft.DirectoryServices.KeyCredential)",
  "value": [
    {
      "keyCredential": {
        "customKeyIdentifier": "6uv7gh",
        "type": "AsymmetricX509Cert",
        "usage": "Verify",
        "value": "MIZB9jVCACfEw="
      },
      "passwordCredential": null,
      "proof": "eyJ0eXAiOiJKv1"
    }
  ]
}

Response List

POST https://graph.windows.net/myorganization/applicationsByAppId/{application_id}/addKey?api-version

Parameters

{
  "keyCredential": {
    "customKeyIdentifier": "6uv7gh",
    "type": "X509CertAndPassword",
    "usage": "Sign",
    "value": "MIIJgIBAzCCCbYGCSqGSIb3gX1MIIF..."
  },
  "passwordCredential": {
    "value": "MKTr0w1ytHhemMDY"
  },
  "proof": "Bearer eyJ0eXAiOiJKv1..."
}

POST https://graph.windows.net/myorganization/applicationsByAppId/1062a13d-f7e5-4ea7-8d24-427f6ff1e5e1/addKey?api-version=1.6

Response

Status Code:200

Content-Type: application/json

{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#Collection(Microsoft.DirectoryServices.KeyCredential)",
  "value": [
    {
      "keyCredential": {
        "customKeyIdentifier": "JXyLFwBmN=",
        "endDate": "2017-10-11T07:00:00Z",
        "keyId": "633b1614-b669-47c5-961e-f4a45978ffff",
        "startDate": "2012-09-11T07:00:00Z",
        "type": "AsymmetricX509Cert",
        "usage": "Sign",
        "value": null
      }
    },
    {
      "keyCredential": {
        "customKeyIdentifier": "JXyLFwBmN=",
        "endDate": "2017-10-11T07:00:00Z",
        "keyId": "633b1614-b669-47c5-961e-f4a45978ffff",
        "startDate": "2012-09-11T07:00:00Z",
        "type": "Password",
        "usage": "Sign",
        "value": null
      }
    }
  ]
}

Response List

Request Body

This request adds a new key credential and password credential to an application. In this example, only a key credential was added to the application.

POST https://graph.windows.net/myorganization/application/8bea0f8d-83eb-4e89-bfca-1f41c8a22ffff/addKey?api-version=1.6 HTTP/1.1
Authorization: Bearer eyJ0eX ... FWSXfwtQ
Content-Type: application/json
Host: graph.windows.net
Content-Length: 406

{ 
  "keyCredential": 
       { 
           "customKeyIdentifier": "6vu7hglDaiwXLbvVeRBIRgSTKXc=", 
            "type": "AsymmetricX509Cert", 
            "usage": "Verify", 
            "value": "MIIB9jCCAVANBgkqhkiG9w0BAQsFADAUMRIwEAYDVQQDEwlEdW..." 
        } 
"passwordCredential": null , 
"proof":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6ImFHZGdvdW5aWlc1bU50Mmg2dmJTM1ZBTHJBVSJ9...." 
} 

As part of the request validation for this service action, a proof of possession of an existing key is verified before the action can be performed. The proof is represented by a self-signed JWT token. The requesting application needs to generate a self-signed JWT token with the following requirements.

Required claims:

• aud - Audience needs to be AAD Graph SPN
• iss - Issuer needs to be one of the application identifier URIs of the application that is making the call or the App ID GUID
• nbf - not before
• exp - expiration time

The X5T, base64 url encoded signing certificate thumbprint header parameter is required

The token signing key is the private key of one of the application existing certificates. The certificate needs to meet the following criteria to be valid:

• Its public key is part of application keys with Asymmetric/Verify type/usage.
• Its public key has not yet expired.

Applications that don’t have any existing valid certificates (i.e.: no certificates have been added yet, or all certificates have expired), won’t be able to use this service action and separate process will be needed to perform an update instead.

The token lifespan should not exceed 10 minutes. Where token lifespan is the difference between EXP and NBF claims.

assignLicense: Add or remove licenses from a user

Call the assignLicense action on a user to add or remove subscriptions for the user. You can also enable and disable specific plans associated with a subscription.

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

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

Parameters

{
  "addLicenses": [
    {
      "disabledPlans": [],
      "skuId": "6fd2c87f-b296-42f0-b197-1e91e994b900"
    }
  ],
  "removeLicenses": []
}

POST https://graph.windows.net/myorganization/users/alexd%40a830edad9050849NDA1.onmicrosoft.com/assignLicense?api-version=1.6

Response

Status Code:200

Content-Type: application/json

none

Response List

Request Body

Note: Subscription SKU IDs and plan IDs can be read from the tenant object. For example, performing a GET request to https://graph.windows.net/myorganization/subscribedSkus returns the subscriptions available for the tenant of the signed-in user. These are returned as SubscribedSku entities and the SKU ID can be read from the skuId property. You can get the plan IDs associated with the subscription from the servicePlans collection. Availability of subscriptions can be calculated from the consumedUnits property and values from the prepaidUnits property, which includes counts of units that are “enabled”, “suspended” and in “warning” states.

Addtitional Examples

This request shows an initial license assignment of the Enterprise Office SKU, which contains SharePoint Online, Lync Online and the Exchange Online service plans.

POST https://graph.windows.net/myorganization/users/[email protected]/assignLicense?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eX ... FWSXfwtQ
Content-Type: application/json
Host: graph.windows.net
Content-Length: 35

{
  "addLicenses":[{"disabledPlans":[ ],"skuId":"6fd2c87f-b296-42f0-b197-1e91e994b900"}],
  "removeLicenses":[ ]
}

This request updates the user’s license by disabling specific plans. In this example, there are two disabledPlans (SharePointOnline and LyncOnline"), leaving only the Exchange Service Plan enabled.

POST https://graph.windows.net/myorganization/users/[email protected]/assignLicense?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eX ... FWSXfwtQ
Content-Type: application/json
Host: graph.windows.net
Content-Length: 35

{ 
  "addLicenses":[  { "disabledPlans":  [”5dbe027f-2339-4123-9542-606e4d348a72”,
                                        “0feaeb32-d00e-4d66-bd5a-43b5b83db82c” ], 

                      "skuId":"6fd2c87f-b296-42f0-b197-1e91e994b900"
                   }  

                 ],
   "removeLicenses":[ ]

 }

This final request shows how to remove the license from the user.

POST https://graph.windows.net/myorganization/users/[email protected]/assignLicense?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eX ... FWSXfwtQ
Content-Type: application/json
Host: graph.windows.net
Content-Length: 35

{
  "addLicenses":[ ],

  "removeLicenses":["6fd2c87f-b296-42f0-b197-1e91e994b900"]
}

changePassword: Change password of the signed-in user

Call the changePassword action for the signed-in user to change their own password.

Note: This action can only be called on the signed-in user. In addition to addressing the operation by using the me alias as shown below, you can use /users/<objectId>/changePassword or /users/userPrincipalName/changePassword, but if you use these addressing modes, the target user must be the signed-in user.

Important: Requires version 1.6 or newer.

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

Parameters

{
  "currentPassword": "Test1234!",
  "newPassword": "Test5678!"
}

Response

Status Code:204

Content-Type: application/json

none

Response List

Request Body

Response Body

None.

removeKey: Remove a KeyCredential for an application

Call the removeKey action on an application to remove a KeyCredential.

Important: Requires version v1.6 or newer.

POST https://graph.windows.net/myorganization/applications/{application_oid}/removeKey?api-version

POST https://graph.windows.net/myorganization/applications/{application_oid}/removeKey?api-version=1.6

Response

Status Code:204

Content-Type: none

none

Response List

POST https://graph.windows.net/myorganization/applicationsByAppId/{application_id}/removeKey?api-version

POST https://graph.windows.net/myorganization/applicationsByAppId/1062a13d-f7e5-4ea7-8d24-427f6ff1e5e1/removeKey?api-version=1.6

Response

Status Code:204

Content-Type: none

none

Response List

Request Body

This request adds a new key credential and password credential to an application. In this example, only a key credential was added to the application.

POST https://graph.windows.net/myorganization/application/8bea0f8d-83eb-4e89-bfca-1f41c8a22ffff/removeKey?api-version=1.6 HTTP/1.1
Authorization: Bearer eyJ0eX ... FWSXfwtQ
Content-Type: application/json
Host: graph.windows.net
Content-Length: 166

{ 
    "keyId": "739c5e5b-ebcc-43b5-b44a-459e1b4dffff", 
    "proof":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6ImFHZGdvdW5aWlc1bU50Mmg2dmJTM1ZBTHJBVSJ9...." 
} 

As part of the request validation for this service action, a proof of possession of an existing key is verified before the action can be performed. The proof is represented by a self-signed JWT token. The requesting application needs to generate a self-signed JWT token with the following requirements.

Required claims:

• aud - Audience needs to be AAD Graph SPN
• iss - Issuer needs to be one of the application identifier URIs of the application that is making the call or the App ID GUID
• nbf - not before
• exp - expiration time

The X5T, base64 url encoded signing certificate thumbprint header parameter is required

The token signing key is the private key of one of the application existing certificates. The certificate needs to meet the following criteria to be valid:

• Its public key is part of application keys with Asymmetric/Verify type/usage.
• Its public key has not yet expired.

Applications that don’t have any existing valid certificates (i.e.: no certificates have been added yet, or all certificates have expired), won’t be able to use this service action and separate process will be needed to perform an update instead.

The token lifespan should not exceed 10 minutes. Where token lifespan is the difference between EXP and NBF claims.

restore: Restore a deleted application

Call the restore action on a deleted application to restore it to the directory.

Note: You can find deleted applications by reading the deletedApplications resource collection. For example, performing a GET to the following URL returns the deleted applications associated with the organization: https://graph.windows.net/myorganization/deletedApplications?api-version=1.5.

Important: Requires version 1.5 or newer.

POST https://graph.windows.net/myorganization/deletedApplications/{application_id}/restore?api-version

Parameters

{
  "identifierUris": [
    "https://restoredApp/"
  ]
}

POST https://graph.windows.net/myorganization/deletedApplications/1e22de0f-0ed1-4c01-b725-a822632467e3/restore?api-version=1.6

Response

Status Code:200

Content-Type: application/json

{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#directoryObjects/Microsoft.DirectoryServices.Application/@Element",
  "odata.type": "Microsoft.DirectoryServices.Application",
  "objectType": "Application",
  "objectId": "1e22de0f-0ed1-4c01-b725-a822632467e3",
  "deletionTimestamp": null,
  "appId": "f4ecf40c-e94f-4d79-af83-f920f81bcb66",
  "appRoles": [],
  "availableToOtherTenants": false,
  "displayName": "Sample App 1",
  "errorUrl": null,
  "groupMembershipClaims": null,
  "homepage": "https://localhost",
  "identifierUris": [
    "https://restoredApp/"
  ],
  "keyCredentials": [],
  "knownClientApplications": [],
  "logoutUrl": null,
  "oauth2AllowImplicitFlow": false,
  "oauth2AllowUrlPathMatching": false,
  "oauth2Permissions": [],
  "oauth2RequirePostResponse": false,
  "passwordCredentials": [],
  "publicClient": null,
  "replyUrls": [
    "https://localhost"
  ],
  "requiredResourceAccess": [
    {
      "resourceAppId": "00000002-0000-0000-c000-000000000000",
      "resourceAccess": [
        {
          "id": "311a71cc-e848-46a1-bdf8-97ff7156d8e6",
          "type": "Scope"
        }
      ]
    }
  ],
  "samlMetadataUrl": null
}

Response List

Request Body

Response Body

Additional Resources

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