Jaa

Functions and actions | Graph API reference

  • Artikkeli

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.

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.

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]

Important

Requests sent to the Graph API must be well-formed, target a valid endpoint and version of the Graph API, and carry a valid access token obtained from Azure AD in their Authorization header. For more detailed information about creating requests and receiving responses with the Graph API, see Operations Overview.

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

ParameterTypeValueNotes
URL
application_oidstring

00009987-f6d8-4957-a6ca-7848d986ffff

The object id of the application.
Query
api-versionstring

1.6

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.
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

Status CodeDescription
200OK. Indicates success. Returns the application's new key credential and password credential directory object.

Request Body None.

Response Body

Type Description
Application Application properties for the specified object ID.

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

ParameterTypeValueNotes
URL
application_idstring

1062a13d-f7e5-4ea7-8d24-427f6ff1e5e1

The application ID (GUID) of the application.
Query
api-versionstring

1.6

The version of the Graph API to target. Required.
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

Status CodeDescription
200OK. Indicates success. Returns the application object ID.

Request Body None.

Response Body

Type Description
Application Application properties for the specified object ID.

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

ParameterTypeValueNotes
URL
resource_collectionstring

users

Specifies the resource collection to target. Acceptable values are users, groups, contacts, and servicePrincipals.
resource_idstring

alexd@a830edad9050849NDA1.onmicrosoft.com

Specifies the user, contact, group, or service principal for which membership is to be checked. For contacts, groups, and service principals the entity-identifier should be an object ID (GUID); for users, it can be either the object ID or the user principal name (UPN)..
Query
api-versionstring

1.6

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.
Body

Content-Type: application/json

{
  "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

Status CodeDescription
200OK. Indicates success. The object IDs of the groups in the request that the target user, contact, group, or service principal has either direct or transitive membership in are returned.

Request Body

Property Name Type Required Description
groupIds Collection(Edm.String) Yes A collection that contains the object IDs of the groups in which to check membership. Up to 20 groups may be specified.

Response Body

Property Name Type Description
value Collection(Edm.String) A collection that contains the object IDs of the groups specified in the request that the contact, user, group, or service principal is a member of.

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

ParameterTypeValueNotes
Query
api-versionstring

1.6

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.
Body

Content-Type: application/json

{
  "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

Status CodeDescription
200OK. Indicates success. A collection that contains the extension properties is returned.

Request Body

Property Name Type Required Description
isSyncedFromOnPremises Edm.Boolean No true to specify that only extension properties that are synced from the on-premises directory should be returned; false to specify that only extension properties that are not synced from the on-premises directory should be returned. If the parameter is omitted then all extension properties (both synced and non-synced) are returned.

Response Body

Property Name Type Description
value Collection(ExtensionProperty) A collection that contains the extension properties registered with the directory filtered according to the request.

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

ParameterTypeValueNotes
URL
resource_collectionstring

users

Specifies the resource collection to target. Acceptable values are users, groups, contacts, and servicePrincipals.
resource_idstring

alexd@a830edad9050849NDA1.onmicrosoft.com

Specifies the user, contact, group, or service principal for which group memberships are to be returned. For contacts, groups, and service principals the entity-identifier should be an object ID (GUID); for users, it can be either the object ID or the user principal name (UPN)..
Query
api-versionstring

1.6

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.
Body

Content-Type: application/json

{
  "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

Status CodeDescription
200OK. Indicates success. The object IDs of the groups that the target user, contact, group, or service principal has either direct or transitive membership in are returned.

Request Body

Property Name Type Required Description
securityEnabledOnly Edm.Boolean Yes true to specify that only security groups that the entity is a member of should be returned; false to specify that all groups that the entity is a member of should be returned. Note: The function can only be called on a user if the parameter is true.

Response Body

Property Name Type Description
value Collection(Edm.String) A collection that contains the object IDs of the groups that the contact, user, group, or service principal is a member of.

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

ParameterTypeValueNotes
URL
resource_collectionstring

users

Specifies the resource collection to target. Acceptable values are users, groups, contacts, and servicePrincipals.
resource_idstring

alexd@a830edad9050849NDA1.onmicrosoft.com

Specifies the user, contact, group, or service principal for which group and directory role memberships are to be returned. For contacts, groups, and service principals the entity-identifier should be an object ID (GUID); for users, it can be either the object ID or the user principal name (UPN)..
Query
api-versionstring

1.6

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.
Body

Content-Type: application/json

{
  "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

Status CodeDescription
200OK. Indicates success. The object IDs of the groups and directory roles that the target user, contact, group, or service principal has either direct or transitive membership in are returned.

Request Body

Property Name Type Required Description
securityEnabledOnly Edm.Boolean Yes true to specify that only security groups that the entity is a member of should be returned; false to specify that all groups and directory roles that the entity is a member of should be returned. Note: The function can only be called on a user if the parameter is true.

Response Body

Property Name Type Description
value Collection(Edm.String) A collection that contains the object IDs of the groups and directory roles that the contact, user, group, or service principal is a member of.

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

ParameterTypeValueNotes
Query
api-versionstring

1.6

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.
Body

Content-Type: application/json

{
  "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

Status CodeDescription
200OK. Indicates success. A collection that contains the directory objects that match the search criterea is returned.

Request Body

Property Name Type Required Description
objectIds Collection(Edm.String) Yes The collection of object IDs for which to return objects. You can specify up to 1000 object IDs.
types Collection(Edm.String) No A collection of object types that specifies the set of resource collections (entity sets) to search. If not specified, the default is DirectoryObject, which contains all of the objects in the directory. Any object that derives from DirectoryObject may be specified in the collection; for example: User, Group, ServicePrincipal, and so on. The values are not case sensitive.

Response Body

Property Name Type Description
value Collection(DirectoryObject) A collection of objects found for the specified Object IDs and resource collections.

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

ParameterTypeValueNotes
Query
api-versionstring

1.6

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.
Body

Content-Type: application/json

{
  "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

Status CodeDescription
200OK. Indicates success. Returns true if the user, contact, group, or service principal is a member of the specified group; otherwsie, false.

Request Body

Property Name Type Required Description
groupId Edm.String Yes The object ID of the group to check.
memberId Edm.String Yes The object ID of the contact, group, user, or service principal to check for membership in the specified group.

Response Body

Property Name Type Description
value Edm.Boolean true if the specified user, group, contact, or service principal has either direct or transitive membership in the specified group; otherwise, false.

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

ParameterTypeValueNotes
URL
application_idstring

1062a13d-f7e5-4ea7-8d24-427f6ff1e5e1

The application ID (GUID) of the service principal.
Query
api-versionstring

1.6

The version of the Graph API to target. Required.
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

Status CodeDescription
200OK. Indicates success. Returns the service principal object ID of the specified application ID.

Request Body

None.

Response Body

Property Name Type Description
value Edm.String The Object ID of the service principal with the specified application ID.

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

ParameterTypeValueNotes
URL
domain_namestring

contoso.com

The fully qualified domain name of the target domain. Must be enclosed in single quotes.
Query
api-versionstring

1.6

The version of the Graph API to target. Required.
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

Status CodeDescription
200OK. Indicates success. Returns the Domain object. The isVerified property indicates whether the ownership of the domain has been verified successfully.

Request Body

None.

Response Body

Type Description
[Domain] The domain being verified. The isVerified property indicates whether the ownership of the domain has been verified successfully.

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

Note

Tenant administrators can also add application keys in the Azure portal.

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

Parameters

ParameterTypeValueNotes
URL
application_oidstring

00009987-f6d8-4957-a6ca-7848d986ffff

The object id of the application.
Query
api-versionstring

1.6

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.
Body

Content-Type: application/json

{
  "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

Status CodeDescription
200OK. Indicates success. Returns the application's new key credential and password credential directory object.
POST https://graph.windows.net/myorganization/applicationsByAppId/{application_id}/addKey?api-version

Parameters

ParameterTypeValueNotes
URL
application_idstring

1062a13d-f7e5-4ea7-8d24-427f6ff1e5e1

The application ID (GUID) of the application.
Query
api-versionstring

1.6

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.
Body

Content-Type: application/json

{
  "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

Status CodeDescription
200OK. Indicates success. Returns the application's new key credential and password credential directory object.

Request Body

Property Name Type Required Description
keyCredential KeyCredential Yes The application key credential to add. Note: keyId value should be null.
passwordCredential PasswordCredential Yes The application password credential to add. Note: keyId value should be null.
proof Edm.String Yes A signed JWT token used as a proof of possession of the existing keys.

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

ParameterTypeValueNotes
URL
user_idstring

alexd@a830edad9050849NDA1.onmicrosoft.com

The user ID. Can be the object ID (GUID) or the user principal name (someuser@a830edad9050849NDA1.onmicrosoft.com) of the target user.
Query
api-versionstring

1.6

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.
Body

Content-Type: application/json

{
  "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

Status CodeDescription
200OK. Indicates success. No response body is returned.

Request Body

Property Name Type Required Description
addLicenses Collection(AssignedPlan) Yes A collection of AssignedLicense objects that specify the licenses to add. You can disable plans associated with a license by setting the disabledPlans property on an AssignedLicense object.
removeLicenses Collection(Edm.Guid) Yes A collection of GUIDs that identify the licenses to remove.

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/alexd@a830edad9050849NDA1.onmicrosoft.com/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/alexd@a830edad9050849NDA1.onmicrosoft.com/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/alexd@a830edad9050849NDA1.onmicrosoft.com/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

ParameterTypeValueNotes
Query
api-versionstring

1.6

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.
Body

Content-Type: application/json

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

Response

Status Code:204

Content-Type: application/json

none

Response List

Status CodeDescription
204No Content. Indicates success. No response body is returned.

Request Body

Property Name Type Required Description
currentPassword Edm.String Yes The current password of the signed-in user.
newPassword Edm.String Yes The new password.

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.

Note

Tenant administrators can also remove application keys in the Azure portal.

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

Status CodeDescription
204No Content. Indicates success. No response body is returned.
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

Status CodeDescription
204No Content. Indicates success. No response body is returned.

Request Body

Property Name Type Required Description
keyId Edm.Guid Yes The keyId that identifies the application key credentials to remove.
proof Edm.String Yes A signed JWT token used as a proof of possession of the existing keys.

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

ParameterTypeValueNotes
URL
application_idstring

1e22de0f-0ed1-4c01-b725-a822632467e3

The object ID (GUID) of the application to restore.
Query
api-versionstring

1.6

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.
Body

Content-Type: application/json

{
  "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

Status CodeDescription
200OK. Indicates success. Returns the restored Application object. The identifierUris property in the restored application is set or restored according to the identifierUris collection specified in the request.

Request Body

Property Name Type Required Description
identifierUris Collection(Edm.String) No The collection of identifier URIs for the application. These will be set in the identifierUris property in the restored Application. If the parameter is omitted, the identifierUris property will retain its original value.

Response Body

Type Description
Application The restored application.

Additional Resources

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