canonical: https://jentic.com/apis/azure.com/azure-servermanagement

# Microsoft Azure ServerManagement

Jentic publishes the only available OpenAPI specification for ServerManagement, keeping it validated and agent-ready. The Azure Server Management API exposes the Microsoft.ServerManagement resource provider, which lets agents register on-premises Windows servers as managed nodes, pair them to a gateway, open remote sessions, and run PowerShell commands against them through the Azure control plane. It models gateways, nodes, sessions, and PowerShell sub-sessions, and is the underlying API for the Server Management Tools experience that Microsoft offered for hybrid and Server Core deployments.

## For AI agents

Register Windows nodes against a gateway, open management sessions, and run PowerShell commands on remote servers through the Azure control plane.

## Scope

Does not provision Azure VMs, manage Azure Arc-enabled servers, or run cross-platform commands - use for legacy Server Management Tools gateway and node operations only.

## Capabilities

- Register an on-premises Windows server as a managed node tied to a gateway
- Provision and upgrade Server Management gateways inside a resource group
- Regenerate a gateway profile when its credentials need to be rotated
- Open a management session against a node and tear it down when done
- Start a PowerShell sub-session on top of an active node session
- Invoke PowerShell commands remotely and read their output
- Cancel a long-running PowerShell command on a remote node

## Use cases

### Hybrid Windows Fleet Inventory

Operations teams managing hybrid estates need a single inventory of Windows servers under Azure control. The nodes endpoint at subscription and resource group scope returns every managed node along with the gateway it is attached to, so an agent can build a fleet view that pairs cloud resources with on-premises servers without scraping individual portal pages.

Example prompt: List nodes at subscription scope and return each node's gatewayId, fully qualified domain name, and provisioning state

### Remote PowerShell Automation

Platform engineers run PowerShell remotely against managed Windows servers without exposing WinRM directly to the internet. The pssessions endpoint creates a PowerShell sub-session over an existing node session and the invokeCommand endpoint runs a command and returns its output, giving an agent a controlled remote execution channel that flows through the Azure control plane.

Example prompt: Open a session on the node, create a pssession, then call invokeCommand with the script Get-Service to read the service list back

### Gateway Lifecycle Management

When a Server Management gateway needs upgrading or its credential profile rotated, an agent can drive the lifecycle through the gateways resource. The regenerateprofile endpoint produces a fresh provisioning profile and upgradetolatest moves the gateway to the latest gateway build, both without requiring an admin to log in to the gateway host.

Example prompt: Call regenerateprofile on the named gateway, then upgradetolatest to roll the gateway forward to the current build

### AI Agent Hybrid Ops

An agent built on Jentic uses Server Management to run scoped Windows operations on remote nodes - reading event logs, restarting services, or pulling configuration - without an analyst RDPing into each box. The agent opens a session, runs the command, captures stdout, and closes the session in one tool sequence discovered through Jentic search.

Example prompt: Search Jentic for run powershell on azure managed node, load the schema, and invoke Restart-Service -Name spooler against the target node

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /subscriptions/{subscriptionId}/providers/Microsoft.ServerManagement/nodes | List all managed nodes in the subscription |
| PUT | /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ServerManagement/gateways/{gatewayName} | Create or update a Server Management gateway |
| POST | /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ServerManagement/gateways/{gatewayName}/regenerateprofile | Regenerate the gateway profile credentials |
| POST | /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ServerManagement/gateways/{gatewayName}/upgradetolatest | Upgrade a gateway to the latest build |
| PUT | /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ServerManagement/nodes/{nodeName} | Register a Windows node against a gateway |
| POST | /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ServerManagement/nodes/{nodeName}/sessions/{session}/features/powerShellConsole/pssessions/{pssession}/invokeCommand | Run a PowerShell command on the remote node |

## Key resources

- **gateways** — Provision, list, upgrade, and regenerate the profile of Server Management gateways
- **nodes** — Register Windows servers as managed nodes and list them at subscription or resource group scope
- **sessions** — Open and close management sessions against a registered node
- **pssessions** — Run PowerShell sub-sessions on top of an active node session

## Why Jentic

- **Setup:** Wiring the ServerManagement API by hand means registering an Azure AD app, running the OAuth2 azure_auth implicit flow with the user_impersonation scope against management.azure.com, and chaining the session, PowerShell sub-session, and async command-polling calls yourself. Through Jentic you install once, import ServerManagement from the API Directory, store the Azure service principal credential once, and your agent calls it.
- **Permission scoping:** ServerManagement puts the resource group, gateway, and node names in the URL path (.../gateways/{gatewayName}, .../nodes/{nodeName}/sessions/{session}/...), so a rule can pin your agent to one gateway or node. You choose the operations it may call, so you can allow opening a session and invoking a command while withholding gateway profile regeneration unless you add it.
- **Credential handling:** Your Azure service principal credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'run PowerShell on an Azure managed node' or 'register a Windows server as a managed node', and Jentic returns the matching Microsoft.ServerManagement operation with its input schema so the agent calls the right endpoint directly.

## Related APIs

- **Service Map** — Maps process and connection topology on managed servers
- **Azure Compute Management** — Manages Azure-hosted virtual machines rather than on-premises servers
- **Azure Hybrid Compute (Arc)** — Modern replacement for Server Management - Azure Arc onboards on-premises servers

## FAQ

### Why is there no official OpenAPI spec for ServerManagement?

Microsoft Azure does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call ServerManagement via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the ServerManagement API use?

ServerManagement uses Azure AD OAuth 2.0 with the implicit flow against https://login.microsoftonline.com/common/oauth2/authorize and the user_impersonation scope. When called through Jentic, your AAD client credentials live in your Jentic One instance and the agent receives a short-lived bearer token rather than the raw secret.

### Can I run PowerShell on a remote server with this API?

Yes. Open a node session, then POST to /.../nodes/{nodeName}/sessions/{session}/features/powerShellConsole/pssessions/{pssession}/invokeCommand with the script. The cancel endpoint at the same path lets you abort a long-running command and the response stream returns stdout.

### How do I register an on-premises Windows server as a managed node?

First PUT a gateway under /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ServerManagement/gateways/{gatewayName}, install the gateway profile on a Windows host, then PUT a nodes/{nodeName} resource pointing at the FQDN of the target server with the gatewayId of the gateway you created.

### What are the rate limits for the ServerManagement API?

Azure Resource Manager applies subscription-level throttling - typically 12,000 reads and 1,200 writes per hour per principal - and reports remaining quota in x-ms-ratelimit-remaining-subscription-reads and x-ms-ratelimit-remaining-subscription-writes. Jentic surfaces those headers so agents can pace themselves.

### How do I rotate gateway credentials through Jentic?

Search Jentic for regenerate server management gateway profile, load the schema for POST /.../gateways/{gatewayName}/regenerateprofile, and execute it. The response contains the new profile that you install on the gateway host. The full search, load, and execute pattern is in the Jentic Python SDK after pip install jentic.

### Is Server Management Tools still supported?

Microsoft retired the Server Management Tools portal experience in mid-2020, but the Microsoft.ServerManagement resource provider and this API remain reachable for environments that registered nodes before retirement. Treat new deployments as legacy and prefer Azure Arc for net-new hybrid Windows management.

### Can I limit what my agent is allowed to do with the Server Management API?

Yes. Because you run Jentic One yourself, your own rules decide which Server Management operations and credentials the agent may use. Since the gateway and node names sit in the URL path, you can pin the agent to a single gateway or node and choose the exact operations it may call. For example, you can let it open a session and invoke a PowerShell command while withholding gateway profile regeneration until you explicitly allow it.