API Overview
This section explains how API access works for AZExecute and how to authenticate correctly.
Complete a workflow through REST or MCP
The public API includes reusable selection and validation operations alongside reads and writes. Use the OpenAPI contract for the deployed version, or MCP discovery and workflow guidance, to resolve valid IDs before acting. Each operation still enforces the caller's tenant, role, ownership, direct grants, license and applicable approvals.
| Workflow | How to complete it |
|---|---|
| Request an application | Resolve co-owners by name/email, select API permissions, submit the request and follow its approval/provisioning state. |
| Configure an application | Discover integration resources, validate the selected target and save its configuration. Foundry supports staged delegated setup and automatic secret rotation. |
| Run a task | Read its safe input contract, follow dynamic lookup references, submit selected values, then inspect the returned run ID and status. |
| Author and govern automation | Discover step types and integrations, edit and validate tasks, choose access recipients and approvers, configure run titles and inspect authorized run diagnostics. |
| Manage groups and API access | Find eligible users, groups, service principals or resources, apply the intended assignment and read it back. Group managers retain their resource-scoped permissions. |
| Manage certificates | Inspect templates and access candidates, order certificates and follow operation status. Private keys and credential transfer use the secure REST/portal flow. |
| Manage scripts and machines | Discover repositories and source files, manage Git synchronization, select authorized machines and follow queued operation results. |
| Plan scheduled work | Inspect linked workloads, preview shutdown schedules or groups and read back the saved timing and enabled state. |
| Personal context | Inspect the active identity, profile and groups; read notifications and manage personal preferences. |
| Tenant administration | Use the tenant administration contract for user inventories, settings, integration administration and reports. |
MCP also explains response contracts and related operations. Discovery describes capabilities; a separate authorized read retrieves your data. An accepted request or queued run is not completion, and a denied lookup is not evidence that a person or resource does not exist.
Credential entry, private-key transfer, backups and billing operations remain outside the MCP tool surface. Use the documented REST or secure portal operation where available. Browser sessions, push subscriptions and connected-agent transport are not general public automation endpoints. Azure DevOps configuration supports the service principal only; PAT entry and the authentication-mode switch have been removed.
Terraform Provider
Create governed Microsoft Entra application requests as code while retaining AZExecute approval, metadata, permission, registration, and deletion policy. The product guide explains the supported lifecycle and links to the complete official provider reference on the Terraform Registry.
MCP for AI agents
Authorized AI agents can connect to the remote MCP endpoint and use the supported customer API through the same Microsoft Entra identity, tenant boundary, and API roles used by REST clients.
For assistants used by people, start with delegated MCP access in each user's context. The guide covers creating the OAuth connection, adding it as an agent tool, each user's sign-in, access verification, and automatic client secret rotation. Use an agent identity when you deliberately want a shared operational role.
MCP provides searchable operation discovery, detailed input contracts, dedicated automation-task tools, and safe invocation of documented operations. Agents can also create and configure saved tasks using typed step schemas and enabled integration references. Publication is optional; see workflow authoring with integrations.
Authentication Model
The API uses Microsoft Entra ID with OAuth 2.0 / OpenID Connect. Clients authenticate against Entra ID and call API endpoints with a bearer token in the Authorization header.
How To Call the API
1. Register or use an approved client identity in Entra ID
2. Request an access token for the AZExecute API audience
3. Send requests with Authorization: Bearer <token>
4. Handle 401/403 responses by revalidating token and permissions
For endpoint-specific examples and role requirements, continue with the API documentation pages in this section.
Explore the Public API
The live Swagger documentation is the authoritative reference for supported endpoints, HTTP methods, parameters, request bodies, response schemas, and required roles.
Start with Authenticate to obtain a token, then use Swagger to select an operation and inspect its exact contract before calling it.
Application workflow lookups and preferences
These supported REST operations are available to your own applications, scripts and integrations as well as MCP clients. Use the same bearer-token authentication and active-tenant context described above. Public API availability does not grant additional roles, ownership or directory permissions.
| Operation under /api/v1 | Purpose |
|---|---|
GET Application/CoOwnerCandidates?search=... | Resolve a name, email or sign-in name to an Entra user object ID for an application request's coOwnerUserIds. Returns up to 100 candidates; narrow broad searches. |
GET Application/PermissionRequests/TenantApplications?search=... | Find enterprise applications as API permission targets using a name prefix or exact client/object ID. Use 2–200 characters; returns up to 25 matches. Pass the returned appId as targetExternalApiAppId to the External permission-options endpoint, then select actual permission IDs. |
PUT Application/{applicationId}/Administrators/{userId}/Notifications | Set notificationsEnabled to true or false for an existing owner of this application. Requires application-management access and returns 204 when saved. It does not change ownership or global user preferences. |
PermissionRequests/ExternalApis lists common APIs; PermissionRequests/TenantApplications searches other enterprise applications in the active tenant using its configured Application integration. Its objectId is a service-principal object ID, not the target client ID or an AZExecute application entity ID. Search results do not grant API access. Inspect the permission-options contract before submitting a request.
The separate GET TenantAdmin/Users inventory requires TenantAdmin access and lists AZExecute tenant users, rather than the entire Entra directory. See application requests and user resolution for the complete workflow and identity distinctions. Each REST contract is also discoverable through MCP in the deployed API catalog.
Application identifiers
For /api/v1/Application/{applicationId} and its application-scoped subroutes, the route parameter accepts any of these GUIDs from the application list. The same rule applies to reads, updates, and deletion, including calls through MCP.
| Response field | Meaning |
|---|---|
id | AZExecute's internal application GUID |
applicationObjectId | Entra application registration Object ID |
applicationId | Entra Application (client) ID |
A servicePrincipalId identifies the enterprise application's service principal and is not an accepted alias. Names and old integer IDs are not accepted. Other parameters, such as targetApplicationEntityId, targetExternalApiAppId, and IDs in import or Terraform contracts, retain their documented meanings.
Find the application with GET /api/v1/Application?search=test12, then verify its name and identifiers with GET /api/v1/Application/<identifier> before changing it. ID matching stays within the authenticated tenant and caller's visibility. A 404 means no visible match, not proof of deletion. A 409 with code ambiguous_application_identifier means more than one visible application matched; no action is performed. Use another unambiguous identifier from a fresh read.
DELETE /api/v1/Application/<identifier> defaults to hardDelete=false, which marks the application deleted. Only use hardDelete=true when you intend to delete the application and its Azure objects. Removing an already deleted AZExecute record uses the separate TenantAdmin-only /Purge operation. Resolving an ID does not grant deletion permission: the existing TenantAdmin or owner-and-tenant-setting checks still apply.