Loading…
Loading documentation...
Mint a least-privilege sau_ Personal Access Token across 23 scopes and call the 140-path Servers Are Up REST API v1 safely.
Commands checked on 2026-11-12 with Servers Are Up REST API v1 (OpenAPI 3.1), curl 8.5, jq 1.7.
You will have a least-privilege sau_ Personal Access Token stored safely outside source code, verified connectivity against zero-auth discovery endpoints and authenticated /api/v1/* routes (140 OpenAPI paths, 222 operations), and working patterns for Idempotency-Key headers, rate-limit inspection, and error handling.
/dashboard (or an organization workspace where you hold Owner/Admin rights).curl and jq installed in your terminal.https://serversareup.com/api/v1 (machine-readable OpenAPI 3.1 spec at https://serversareup.com/openapi.json).Several v1 endpoints require no authentication at all so scripts and AI agents can inspect API health, live catalog pricing, and workload recommendations immediately:
curl -fsSL "https://serversareup.com/api/v1/version" | jq .
curl -fsSL "https://serversareup.com/api/v1/catalog?type=VM" | jq '.products[:3] | map({slug, name, priceCents, purchasable})'
curl -fsSL "https://serversareup.com/api/v1/recommend?workload=linux-standard&budgetUsd=35" | jq '.recommendations[0]'
sau_...)Open Account settings > API keys (/account/api-keys)—or /orgs/<id>/admin/api-keys for an organization-scoped token—and click Create API key:
github-actions-deploy or laptop-sau-cli).30 or 90 days recommended for CI/CD runners).* scopes are explicitly rejected with 400 Bad Request so no token silently bypasses authorization):instances:read, instances:write, instances:power, instances:exec, instances:files:read, instances:files:writesnapshots:read, snapshots:writenetwork:read, network:write, ssh-keys:read, ssh-keys:writestorage:read, storage:write, billing:read, billing:write, catalog:readcloud:read, cloud:write (covers /api/v1/resource-manager, /cosmos, /blob-storage, /vault/*, /sentinel, /defender-purview, /entra-suite, /apim, /cloud-dns, /serverless-compute, /workflows, /app-config, /service-bus, /iot-chaos, /governance, /recovery-vault, and /cloud-services)account:read, activity:read, usage:read, webhooks:read, webhooks:write (isos:read/isos:write are legacy compatibility scopes)Copy the sau_... secret immediately—the server stores only its cryptographic hash and prefix, so the plaintext secret is never shown again.
Export SAU_API_TOKEN in your terminal session (prefix the export with a leading space in bash/zsh if HISTCONTROL=ignorespace is enabled) and query your account, servers, and Resource Groups:
export SAU_API_TOKEN="sau_your_token_here"
# Inspect token owner and organization context (account:read)
curl -fsSL "https://serversareup.com/api/v1/account" \
-H "Authorization: Bearer ${SAU_API_TOKEN}" | jq .
# List your servers (instances:read)
curl -fsSL "https://serversareup.com/api/v1/instances" \
-H "Authorization: Bearer ${SAU_API_TOKEN}" | jq '.instances | map({id, name, status, publicIp})'
# List Resource Groups and active Management Locks (cloud:read)
curl -fsSL "https://serversareup.com/api/v1/resource-manager?section=overview" \
-H "Authorization: Bearer ${SAU_API_TOKEN}" | jq '{groups: (.resourceGroups | length), locks: (.locks | length)}'
Idempotency-Key workKeep four important API contracts in mind when writing automation:
POST /api/v1/instances answers 405 Method Not Allowed. New catalog servers are purchased through POST /api/v1/orders (or its alias POST /api/v1/deploy) with billing:write + instances:write scopes and a unique Idempotency-Key header (8–200 chars) so network retries never double-charge.PATCH /api/v1/instances/{id} updates name and tags (hostname in PATCH returns 400 Bad Request).DELETE /api/v1/instances/{id}) enqueue a durable provider command and return 202 Accepted.ReadOnly or CanNotDelete lock, destructive POST/DELETE mutations return 409 Conflict (RESOURCE_LOCKED) before touching infrastructure.# Rename a server and attach structured tags (instances:write)
curl -fsSL -X PATCH "https://serversareup.com/api/v1/instances/YOUR_INSTANCE_ID" \
-H "Authorization: Bearer ${SAU_API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"name":"prod-api-01","tags":["env:prod","tier:backend"]}' | jq .
Verify both a 200 OK authorized call and inspect rate-limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) on the response:
curl -fsSI "https://serversareup.com/api/v1/instances" \
-H "Authorization: Bearer ${SAU_API_TOKEN}" | grep -iE "^HTTP/|^x-ratelimit"
Open Operations > Activity log (/dashboard/activity) (or run sau monitor activity-log) to see your API token calls recorded in your tenant audit trail.
401 Unauthorized even after pasting the token. Check for trailing newlines when base64-decoding secrets in CI (echo -n "$TOKEN" instead of echo), confirm the header reads Authorization: Bearer sau_..., and verify you are calling https://serversareup.com/api/v1/....403 Forbidden with insufficient_scope. The error JSON names the exact missing scope (for example cloud:write or instances:power). Mint a replacement token on /account/api-keys with that scope rather than reusing an over-privileged admin token everywhere.429 Too Many Requests during parallel fleet scripts. Read the Retry-After response header and back off exponentially with jitter rather than retrying in a tight loop.instances:read, cloud:read, activity:read) from mutating deployment tokens so dashboards, AI assistants, and monitoring scripts cannot alter production state.Idempotency-Key header on POST /api/v1/orders, POST /api/v1/deploy, and permanent instance deletions.https://serversareup.com/openapi.json (note that standalone Python, Node.js, and Go SDK packages on PyPI/npm are Coming soon and not published today—use direct fetch/httpx, @serversareup/cli, or @serversareup/mcp-server).Every Servers Are Up virtual machine and container includes an integrated HTML5 browser-based SSH, RDP, and VNC console in your dashboard, default-off inbound firewall rules with per-IP allow-lists, and full programmatic control via REST API v1 and Model Context Protocol (MCP). Explore our Virtual Datacenter Plans or reach out to Servers Are Up Support.