Build on the control plane

Integrations authenticate with a rugged.sh API key — a partner-scoped service-account credential. These are not Microsoft/Graph keys: you never handle Microsoft secrets. Send it as a bearer token:

curl -H "Authorization: Bearer mspm_XXXXXXXX..." \
  https://api.rugged.sh/api/tenants

Create and rotate keys in the console under Settings → API keys. The secret (mspm_ + 32 random bytes) is shown once at creation and never stored — only a hash + a display prefix. The console itself uses a session cookie from POST /api/auth/login.

A key carries optional scopes and a tenant allow-list. Scope families includetenants,deployments,autoscale,drift,apps,billing,rugglets,team. Reads need<family>:read, mutations need <family>:write. A tenant allow-list restricts the key to specific customers. Every row is partner-isolated; cross-partner access is a 404.

• Roles: viewer < operator < admin < owner. Reads are Viewer+, mutations Operator+, settings/team/keys Admin+.
• Errors: non-2xx returns {"error":"message"}. 401 unauthenticated · 403 role/scope/tenant denied · 404 not found or cross-partner · 409 conflict · 429 rate-limited (honor Retry-After).
• Pagination: growable lists take ?limit=&cursor= and return the next cursor in the X-Next-Cursor header.
• Idempotency: deploys and migration commits accept a correlationId — resubmitting is a safe replay.

The integration surface is a curated, tenant-scoped subset of the API for wiring your own systems — reading fleet/governance/cost and driving deployments for the customers you manage. Internal operator and platform endpoints are not part of it.

The machine-readable OpenAPI 3.1 reference is available to signed-in customers at GET /api/openapi.json(bring your session or an API key). Point Postman, Swagger UI, or your codegen at it.

Kick an AVD deployment with a key that has deployments:write:

curl -X POST https://api.rugged.sh/api/deployments \
  -H "Authorization: Bearer mspm_XXXX..." \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "contoso",
    "templateId": "pooled-desktop",
    "region": "eastus2",
    "seats": 50,
    "vmSize": "Standard_D4as_v5",
    "imageRef": "MicrosoftWindowsDesktop:windows-11:win11-24h2-avd:latest",
    "correlationId": "my-deploy-1"
  }'