ARM API reference

The App Service Builder ARM contract manages Microsoft.Web/builderApps resources and their deployment and authentication actions.

At a glance

• Authenticate with an Azure Resource Manager token and authorized Azure RBAC context.
• Include a supported api-version on every request.
• Use sparse PATCH for source, variables, and identity.
• Follow asynchronous operation URLs for deployment and deletion.

Base URL and version

Use the Azure public-cloud ARM request origin:

https://management.azure.com

The current API version is 2026-09-01-preview. Public ARM also accepts 2026-08-01-preview. The Builder CLI uses 2026-09-01-preview; the Portal uses 2026-08-01-preview for source and selected-version deployments. Confirm subscription access and location with your preview contact before making requests.

In the table below, {app} means:

/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/Microsoft.Web/builderApps/{name}

Operations

Method	Path	Contract
PUT	{app}	Create or update; requires location and properties
GET	{app}	Desired app state and runtime IDs/URL, without source credentials or variable values
PATCH	{app}	Presence-aware source, version variables, and identity update
DELETE	{app}	Asynchronous app deletion
GET	App collection under resource group	List apps in that group
GET	/subscriptions/{subscriptionId}/providers/Microsoft.Web/builderApps	List apps in subscription
POST	{app}/deploy	Resolve source and reuse/build, or deploy the retained versionId
POST	{app}/redeploy	Deploy retained ready artifacts without a new build
GET	{app}/operationStatuses/{deploymentId}	Read deployment operation outcome
GET	{app}/identityOperationStatuses/{operationId}	Read identity save and linked deployment outcome
POST	{app}/listVariables	Read sensitive desired variable values with action authorization
GET, PUT, DELETE	{app}/authConfigs/current	Read/replace/reset deployed-app authentication

Every URL needs an accepted api-version query parameter. Use Portal or Builder CLI for version history, build logs, and deployment history. Those operations are not ARM collection routes in this table.

Desired state

Field	Write behavior
location	Required for PUT
tags	Optional PUT resource tags
properties.source	GitHub source identity, reference, app root, and optional write-only authorization
properties.versionConfiguration.variables	Complete desired variable-name list with preserve/replace value semantics
properties.source.autoDeploy	Automatic-deployment policy; keep false for the current explicit-deployment preview workflow
properties.telemetry.azureMonitorLogs	PUT an Azure Monitor Logs destination where runtime log export and its required identity are configured
properties.scaling.components	PUT app-owned CPU/memory policy by component name
identity	PUT replaces assignments; PATCH merges desired identity fields

Do not send server-derived source, runtime, system metadata, or component build facts as writable fields. PATCH omits unrelated fields to preserve them. Explicit null source, variable list, or identity is not a removal operation. To clear variables send []; to remove identity use type: "None". PATCH accepts the automatic-deployment policy inside properties.source, but does not accept scaling or telemetry. For PUT updates, preserve the other desired writable fields you intend to keep.

GitHub source fields

properties.source field	Meaning
provider	GitHub
id	Numeric GitHub repository ID, represented as a string
displayName	Canonical owner/repository
reference	Branch or source reference
rootDirectory	Repository-relative app root; omitted or . means repository root
autoDeploy	Reads as off unless true; on update, write false to disable because omission or null preserves the current setting
repositoryToken	Write-only authorized GitHub user credential
authorizationToken	Write-only, target-bound authorization assertion; mutually exclusive with repositoryToken

After connection, the provider and repository identity cannot be removed or replaced. Create another app for another repository. Attaching source, changing its branch or app root, or reauthorizing it requires fresh caller-bound authorization. An update that preserves the authorized branch and app root can omit the credential. PATCH preserves omitted fields; source: null is not a removal operation.

Runtime log export

properties.telemetry.azureMonitorLogs configures runtime stdout/stderr export to a customer-owned Azure Monitor Logs destination. This is separate from reading build or deployment logs in the Portal. Confirm with your preview contact that it is enabled for your environment.

Field	Value
dceEndpoint	HTTPS data collection endpoint under *.ingest.monitor.azure.com, using port 443 with no path beyond /, query, or fragment
dcrImmutableId	Data collection rule immutable ID: dcr- followed by 32 lowercase hexadecimal characters
streamName	A declared DCR stream beginning with Custom-, followed by a letter and then letters, digits, or underscores
identityResourceId	Omit or set to null to use the app's system-assigned identity; otherwise, select a user-assigned identity already attached to the app

Hosted export uses the app's managed identity and requires the system-assigned identity to be enabled, even when selecting an attached user-assigned identity. Grant the selected identity permission to ingest through the destination DCR. Builder does not create the workspace, table, endpoint, rule, or role assignment for you.

Omitting telemetry preserves the destination. Sending "telemetry": {} clears it. Use PUT and preserve the app's other desired fields; PATCH does not accept telemetry. Updates are rejected while a deployment is in progress. Without an active web runtime, the destination takes effect on the next deployment. For an active runtime, it is applied without rebuilding the source or creating an app version. An accepted update does not prove ingestion; verify new log records in the destination workspace.

See Send runtime logs to Azure Monitor Logs for prerequisites, setup, and verification.

Deployment request

{
  "idempotencyKey": "<unique-request-id>",
  "rebuild": true
}

rebuild is optional. To deploy an explicit revision, use commitSha with a full 40-character hexadecimal SHA instead of rebuild. Do not combine them. commitSha is supported on deploy, not retained-artifact redeploy. To deploy a retained ready version, send versionId instead of commitSha or rebuild. versionId cannot be combined with commitSha, rebuild, or uploaded source. This creates a fresh deployment from the version's frozen configuration and retained outputs, without rebuilding or requiring current source authorization. The former activation endpoint is removed. Update older clients and scripts to use deploy.versionId; the service does not fall back to the retired operation. Selected-version deployment requires the updated service; this change does not introduce a new API version.

Supply idempotencyKey or x-ms-client-request-id. The response returns 202 Accepted, a deployment ID, Azure-AsyncOperation, and Retry-After. Use the returned operation URL rather than constructing it. Continue authenticated polling until terminal; acceptance alone proves neither build readiness nor serving activation.

ZIP-source contract

ZIP deployment uploads source to build with its root builder.yaml. Follow Deploy ZIP source for the procedure. Upload requests use the customer's Entra access token for Azure Resource Manager. The upload path does not yet accept dedicated Builder-audience tokens. The token's tenant and principal must match the caller that began the session; an upload URL alone does not authorize access.

The flow begins with POST {app}/beginSourceUpload, uploads bytes through the returned authenticated upload URL, then submits source to {app}/deploy. It does not change the app's durable GitHub source connection.

Begin-upload field	Contract
idempotencyKey	UUID; replay requires the same caller, app lifecycle, archive length/digest, and planning-manifest digest
manifestYaml	Exact root builder.yaml text; at most 1 MiB of UTF-8; validated using the existing manifest rules
contentLength	Compressed archive bytes, from 1 byte through 100 MiB
sha256	Lowercase 64-character SHA-256 of those archive bytes
origin	Optional repository/workflow/run provenance; not an authorization credential

source identifies kind: "uploadedArtifact", artifactId, sha256, and contentLength from that session. It cannot be combined with commitSha, rebuild, or versionId.

The response supplies separate upload and uncommitted deadlines. Upload must finish before the upload deadline, and first deployment admission must occur before the uncommitted deadline. If an admission response is lost after the immutable version was created, the same caller can replay the same deployment after that deadline while its source is retained. Recovery requires that version to match the app lifecycle, artifact ID, archive and manifest digests, and byte count. A bound session alone does not extend admission, and a different deployment cannot reuse it. Session replay metadata is retained for 30 days after source cleanup and quota release; it is not an indefinite idempotency record.

An uploaded state is not build success. Builder extracts ordinary unencrypted ZIPs and verifies root builder.yaml against the exact submitted UTF-8 bytes before building. Malformed/corrupt ZIPs and missing, oversized, or mismatched manifests fail the asynchronous deployment with SourceUploadArchiveInvalid. Begin-upload manifest parsing/topology failures return AppManifestInvalid.

GitHub source permission denial returns 403 SourceAuthorizationFailed; check the GitHub connection and repository permissions. 500 ArmAuthorizationContextUnavailable is a service failure; if it persists, contact your preview team instead of repeatedly signing in.

Reads and concurrency

properties.runtime.activeAppVersionId and activeDeploymentId identify the serving selection. properties.provisioningState describes resource provisioning, not by itself deployment success. Variable names on ordinary GET are not value receipts.

Authentication PUT accepts If-Match and If-None-Match; DELETE accepts If-Match. Use the returned authentication ETag for guarded editing. If a response is lost, read back and reconcile before retrying an unrelated mutation. Respect Retry-After for pending-work conflicts.

Managed identity contract

See managed identity for how identities work in Builder.

Field or update	Meaning
identity.type	None, SystemAssigned, UserAssigned, or SystemAssigned,UserAssigned
identity.userAssignedIdentities	Map keyed by full Microsoft.ManagedIdentity/userAssignedIdentities resource IDs
User-assigned map value {}	Assign that identity; assignment permission is required
User-assigned map value null in PATCH	Remove that assignment while preserving the others
Omitted identity	Preserve current assignment
identity: null	Invalid input
PUT identity	Replace assignments
PATCH identity	Merge assignments; selecting SystemAssigned removes user-assigned assignments
identity.principalId	Returned system-assigned principal ID
Returned user-assigned metadata	Generated clientId and principalId; do not supply those IDs as assignment input

UserAssigned requires a nonempty assignment map. When removing the last user-assigned identity, select SystemAssigned or None as appropriate. type: "None" removes assignments. Running compute must be deployed or redeployed after an assignment change. An identity-only PATCH returns 202 Accepted after durable admission, with properties.identityUpdate, Azure-AsyncOperation, and Retry-After. The backend saves the source assignment and submits retained-artifact redeployment without another client request. Poll the returned operation URL until terminal; source save and deployment acceptance do not establish runtime completion. App GET exposes the latest identity operation so a client can recover after a lost response or reload. The top-level identity reports committed source state, not the pending target.

A matching pending target rejoins the existing operation; a contradictory identity write conflicts. Rejoining a pending deployment handoff uses its committed source checkpoint; a fresh authenticated retry reapplies the source assignment. NoBuildArtifacts means an identity-only update is saved but an initial deployment is required; it does not silently build from GitHub. Initial creation, PUT, and PATCH combined with other settings preserve their configuration-save semantics and require an explicit deployment. A later identity write replaces or retires the latest operation projection. Its polling URL still resolves through a compact receipt for the 32 most recent retired operations in the current app lifecycle, using the original deployment's canonical status. Unknown or evicted IDs and IDs from a deleted-and-recreated app return 404.

To set AZURE_CLIENT_ID with an identity assignment, include properties.azureClientIdIdentityResourceId in the identity PATCH. It must identify a user-assigned identity in the resulting assignment, and cannot be combined with source or version-configuration fields. The operation resolves its generated client ID, preserves other variables, and submits one configuration-changing deployment using the normal source build and new-version flow. The operation projection includes the selected resource ID; replay compares both assignment and selection.

Assignment changes do not immediately revoke issued access tokens or delete separately owned user-assigned identities. Use a principal ID for destination role assignments and a client ID when selecting a user-assigned credential in application code.

Authentication configuration

Configure GitHub or managed Microsoft Entra work-account sign-in using a provider available in your preview environment. Managed providers require the environment's provider application to be configured. You can also supply your own GitHub OAuth application. Customer-owned Entra authentication uses a user-assigned managed identity, described below. See authentication and feature status before choosing a provider. GET the current policy and send its ETag in If-Match when replacing it. PUT replaces the policy, so preserve enabled providers and rules you intend to keep.

For example, this policy requires managed Microsoft Entra sign-in and permits accounts from one trusted tenant: Replace <trusted-tenant-id> with that tenant's GUID.

PUT https://management.azure.com/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Web/builderApps/<app-name>/authConfigs/current?api-version=2026-09-01-preview
Authorization: Bearer <arm-access-token>
If-Match: <etag-from-current-read>
Content-Type: application/json

{
  "properties": {
    "mode": "required",
    "primaryBrowserProvider": "entraId",
    "entraId": {
      "enabled": true,
      "applicationMode": "managed",
      "tenantIds": ["<trusted-tenant-id>"]
    }
  }
}

The response includes propagationPending, warnings, and provider callback URLs. Saving updates the policy without a source rebuild; verify actual sign-in after the update finishes.

Field	Values
mode	disabled, optional, or required
primaryBrowserProvider	github or entraId; must be enabled
github.enabled, entraId.enabled	Enable the provider
applicationMode	managed or customer
customerApplication	Customer-owned application settings for that provider

Authentication access rules

Provider	Rule fields
GitHub	emails, emailSuffixes, usernames, usernameSuffixes, numeric userIds
Entra ID	emails, emailSuffixes, objectIds, tenantIds

GitHub rules are alternatives; any match grants access. Entra tenant rules restrict directories, and email/object-ID rules narrow identities within them. An empty allowlist permits all identities accepted by the selected application. A tenant-only rule permits every authenticated identity in that tenant. Each provider permits at most 100 combined entries; customer Entra API audiences count toward the same limit.

For work-account email rules, use trusted tenantIds or configure the xms_edov optional claim in both ID and access tokens of a customer-owned registration. Unpinned work accounts without verified email evidence cannot match email rules. Saving a multi-tenant registration with email rules but no pinned tenants returns a warning. Personal Microsoft account email rules do not require a tenant pin.

Customer-owned GitHub application

Set github.applicationMode to customer and supply customerApplication.clientId and write-only clientSecret. Omitting the secret retains it when the client ID is unchanged. Changing the client ID requires its matching secret. Set the OAuth application's callback to the returned githubCallbackUrl on the app's service-provided hostname. Custom-domain setup is not supported in this preview.

Customer-owned Entra application

Customer-owned Entra authentication requires a user-assigned managed identity assigned to the app. The registration and user-assigned managed identity must belong to the same organizational tenant. The provider object is placed in properties.entraId of the full policy:

{
  "enabled": true,
  "applicationMode": "customer",
  "customerApplication": {
    "clientId": "<application-client-id>",
    "homeTenantId": "<organizational-tenant-id>",
    "signInMode": "singleTenant",
    "workloadIdentityResourceId": "<assigned-user-identity-resource-id>",
    "allowedAudiences": []
  }
}

signInMode	Accounts selected in the registration
singleTenant	This organizational tenant only
organizations	Any organizational tenant
organizationsAndPersonal	Organizational and personal Microsoft accounts
personal	Personal Microsoft accounts only

Even personal sign-in needs an organizational home tenant for the registration and identity. There is no system-assigned identity or client-secret fallback for this credential. The Web redirect URI is the returned entraCallbackUrl; federated credential values come from entraSetup. Use the returned issuer, subject, and audience exactly. Saving does not verify the external registration or federated credential. An empty allowedAudiences list disables customer Entra bearer access; enabled API audiences must be application/client ID GUIDs. Use v2 access tokens and implement application scope/role checks as described in authentication.

Related contracts

The ARM API deployment guide shows create, source authorization, deployment, polling, and deletion in sequence. Authentication, managed identity, variables, and scaling explain the customer choices and availability boundaries.