Namespace: microsoft.graph
Create a new application object if it doesn't exist, or update the properties of an existing application object.
This API can also create an agentIdentityBlueprint object if it doesn't exist, or update properties of an existing agentIdentityBlueprint, when the @odata.type property is set to #microsoft.graph.agentIdentityBlueprint.
This API is available in the following national cloud deployments.
| Global service |
US Government L4 |
US Government L5 (DOD) |
China operated by 21Vianet |
| ✅ |
✅ |
✅ |
✅ |
Permissions
Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.
| Permission type |
Least privileged permissions |
Higher privileged permissions |
| Delegated (work or school account) |
Application.ReadWrite.All |
Not available. |
| Delegated (personal Microsoft account) |
Application.ReadWrite.All |
Not available. |
| Application |
Application.ReadWrite.OwnedBy |
Application.ReadWrite.All |
Important
For delegated access using work or school accounts, the admin must be assigned a supported Microsoft Entra role or a custom role that grants the permissions required for this operation. This operation supports the following built-in roles, which provide only the least privilege necessary:
- A non-admin member or guest who has default user permissions, unless the tenant admin restricted access.
- Application Developer. This role can create apps even when the admin restricted access to members and guests. The principal with this role is assigned ownership of the app they create.
- Directory Writers. This role can update extension properties.
- Hybrid Identity Administrator. This role can update only basic properties.
- Security Administrator
- Cloud Application Administrator
- Application Administrator
In delegated scenarios using work or school accounts, the following privileges are supported for managing agent identity blueprints:
- The signed-in user is the owner, or
- The signed-in user is assigned the Agent ID Administrator role.
HTTP request
To create or update an application, specify the uniqueName client-provided alternate key.
PATCH /applications(uniqueName='{uniqueName}')
| Name |
Description |
| Authorization |
Bearer {token}. Required. Learn more about authentication and authorization. |
| Content-Type |
application/json. Required. |
| Prefer |
create-if-missing. Required for upsert behavior, otherwise the request is treated as an update operation. |
Request body
In the request body, supply a JSON representation of the application object. The request body must contain displayName, which is a required property. Specify other writable properties as necessary for your application, for creation or update.
Response
If an application or agentIdentityBlueprint object with uniqueName doesn't exist, this method returns a 201 Created response code and a new application or agentIdentityBlueprint object with the assigned the uniqueName value in the response body.
If an application or agentIdentityBlueprint object with uniqueName doesn't exist and the Prefer: create-if-missing header is not specified, this method returns a 404 Not Found error code.
If an application or agentIdentityBlueprint object with uniqueName already exists, this method updates the application or agentIdentityBlueprint object and returns a 204 No Content response code.
Examples
Example 1: Create a new application if it doesn't exist
The following example creates an application because an application with the specified uniqueName value doesn't exist.
Request
The following example shows a request.
PATCH https://graph.microsoft.com/v1.0/applications(uniqueName='app-65278')
Content-Type: application/json
Prefer: create-if-missing
{
"displayName": "Display name"
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new Application
{
DisplayName = "Display name",
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.ApplicationsWithUniqueName("{uniqueName}").PatchAsync(requestBody, (requestConfiguration) =>
{
requestConfiguration.Headers.Add("Prefer", "create-if-missing");
});
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
abstractions "github.com/microsoft/kiota-abstractions-go"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
graphapplicationswithuniquename "github.com/microsoftgraph/msgraph-sdk-go/applicationswithuniquename"
//other-imports
)
headers := abstractions.NewRequestHeaders()
headers.Add("Prefer", "create-if-missing")
configuration := &graphapplicationswithuniquename.ApplicationsWithUniqueNameRequestBuilderPatchRequestConfiguration{
Headers: headers,
}
requestBody := graphmodels.NewApplication()
displayName := "Display name"
requestBody.SetDisplayName(&displayName)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
uniqueName := "{uniqueName}"
applications, err := graphClient.ApplicationsWithUniqueName(&uniqueName).Patch(context.Background(), requestBody, configuration)
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
Application application = new Application();
application.setDisplayName("Display name");
Application result = graphClient.applicationsWithUniqueName("{uniqueName}").patch(application, requestConfiguration -> {
requestConfiguration.headers.add("Prefer", "create-if-missing");
});
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Applications(uniqueName='{uniqueName}')\ApplicationsWithUniqueNameRequestBuilderPatchRequestConfiguration;
use Microsoft\Graph\Generated\Models\Application;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new Application();
$requestBody->setDisplayName('Display name');
$requestConfiguration = new ApplicationsWithUniqueNameRequestBuilderPatchRequestConfiguration();
$headers = [
'Prefer' => 'create-if-missing',
];
$requestConfiguration->headers = $headers;
$result = $graphServiceClient->applicationsWithUniqueName('{uniqueName}', )->patch($requestBody, $requestConfiguration)->wait();
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
Import-Module Microsoft.Graph.Applications
$params = @{
displayName = "Display name"
}
Update-MgApplicationByUniqueName -BodyParameter $params
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.applications(unique_name='{unique_name}').applications_with_unique_name_request_builder import ApplicationsWithUniqueNameRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
from msgraph.generated.models.application import Application
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = Application(
display_name = "Display name",
)
request_configuration = RequestConfiguration()
request_configuration.headers.add("Prefer", "create-if-missing")
result = await graph_client.applications_with_unique_name("{uniqueName}").patch(request_body, request_configuration = request_configuration)
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
Response
The following example shows the response.
Note: The response object shown here might be shortened for readability.
HTTP/1.1 201 Created
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#applications/$entity",
"id": "03ef14b0-ca33-4840-8f4f-d6e91916010e",
"deletedDateTime": null,
"isFallbackPublicClient": null,
"appId": "631a96bc-a705-4eda-9f99-fdaf9f54f6a2",
"applicationTemplateId": null,
"identifierUris": [],
"createdDateTime": "2019-09-17T19:10:35.2742618Z",
"displayName": "Display name",
"isDeviceOnlyAuthSupported": null,
"groupMembershipClaims": null,
"optionalClaims": null,
"addIns": [],
"publisherDomain": "contoso.onmicrosoft.com",
"samlMetadataUrl": "https://graph.microsoft.com/2h5hjaj542de/app",
"signInAudience": "AzureADandPersonalMicrosoftAccount",
"tags": [],
"tokenEncryptionKeyId": null,
"api": {
"requestedAccessTokenVersion": 2,
"acceptMappedClaims": null,
"knownClientApplications": [],
"oauth2PermissionScopes": [],
"preAuthorizedApplications": []
},
"appRoles": [],
"publicClient": {
"redirectUris": []
},
"info": {
"termsOfServiceUrl": null,
"supportUrl": null,
"privacyStatementUrl": null,
"marketingUrl": null,
"logoUrl": null
},
"keyCredentials": [],
"parentalControlSettings": {
"countriesBlockedForMinors": [],
"legalAgeGroupRule": "Allow"
},
"passwordCredentials": [],
"requiredResourceAccess": [],
"uniqueName": "app-65278",
"web": {
"redirectUris": [],
"homePageUrl": null,
"logoutUrl": null,
"implicitGrantSettings": {
"enableIdTokenIssuance": false,
"enableAccessTokenIssuance": false
}
},
"windows" : null
}
Example 2: Update an existing application
The following example updates the application because an application with the specified uniqueName value exists.
Request
The following example shows a request.
PATCH https://graph.microsoft.com/v1.0/applications(uniqueName='app-65278')
Content-Type: application/json
Prefer: create-if-missing
{
"displayName": "Display name"
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new Application
{
DisplayName = "Display name",
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.ApplicationsWithUniqueName("{uniqueName}").PatchAsync(requestBody, (requestConfiguration) =>
{
requestConfiguration.Headers.Add("Prefer", "create-if-missing");
});
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
abstractions "github.com/microsoft/kiota-abstractions-go"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
graphapplicationswithuniquename "github.com/microsoftgraph/msgraph-sdk-go/applicationswithuniquename"
//other-imports
)
headers := abstractions.NewRequestHeaders()
headers.Add("Prefer", "create-if-missing")
configuration := &graphapplicationswithuniquename.ApplicationsWithUniqueNameRequestBuilderPatchRequestConfiguration{
Headers: headers,
}
requestBody := graphmodels.NewApplication()
displayName := "Display name"
requestBody.SetDisplayName(&displayName)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
uniqueName := "{uniqueName}"
applications, err := graphClient.ApplicationsWithUniqueName(&uniqueName).Patch(context.Background(), requestBody, configuration)
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
Application application = new Application();
application.setDisplayName("Display name");
Application result = graphClient.applicationsWithUniqueName("{uniqueName}").patch(application, requestConfiguration -> {
requestConfiguration.headers.add("Prefer", "create-if-missing");
});
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Applications(uniqueName='{uniqueName}')\ApplicationsWithUniqueNameRequestBuilderPatchRequestConfiguration;
use Microsoft\Graph\Generated\Models\Application;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new Application();
$requestBody->setDisplayName('Display name');
$requestConfiguration = new ApplicationsWithUniqueNameRequestBuilderPatchRequestConfiguration();
$headers = [
'Prefer' => 'create-if-missing',
];
$requestConfiguration->headers = $headers;
$result = $graphServiceClient->applicationsWithUniqueName('{uniqueName}', )->patch($requestBody, $requestConfiguration)->wait();
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
Import-Module Microsoft.Graph.Applications
$params = @{
displayName = "Display name"
}
Update-MgApplicationByUniqueName -BodyParameter $params
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.applications(unique_name='{unique_name}').applications_with_unique_name_request_builder import ApplicationsWithUniqueNameRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
from msgraph.generated.models.application import Application
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = Application(
display_name = "Display name",
)
request_configuration = RequestConfiguration()
request_configuration.headers.add("Prefer", "create-if-missing")
result = await graph_client.applications_with_unique_name("{uniqueName}").patch(request_body, request_configuration = request_configuration)
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
Response
The following example shows the response.
HTTP/1.1 204 No Content