azd rest

Authenticated Azure REST Calls

Make REST API calls with automatic Azure authentication and scope detection — no manual token management.

🌐 Visit the Website →

Full documentation, CLI reference, and security architecture

📦 Part of azd Extensions →

Browse all Azure Developer CLI extensions by Jon Gallant

---

⚡ One-Command REST Calls

Stop managing tokens. Run azd rest and authentication happens automatically.

# Add the extension registry
azd extension source add -n jongio -t url -l https://jongio.github.io/azd-extensions/registry.json

# Install the extension
azd extension install jongio.azd.rest

# Make your first request
azd rest get https://management.azure.com/subscriptions?api-version=2020-01-01

That's it. The extension detects the correct OAuth scope, acquires tokens, handles retries, and formats JSON responses.

---

✨ Features

🔐 Automatic Authentication Uses your azd credentials and reads the hostname to pick the right OAuth scope: Management API, Graph, Key Vault, Storage, Cosmos DB, and more. 🛡️ Security Hardened SSRF protection with DNS resolution validation, blocked CIDR ranges, rate limiting, header sanitization, and response size limits. See security architecture → 🤖 MCP Server Built-in Model Context Protocol server for AI agent integration. Copilot and other AI tools can make authenticated Azure REST calls through azd rest.

🔄 All HTTP Methods GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, and custom methods through request <method> <url> with JSON body support from inline data or files. 📊 Verbose Diagnostics Request/response details, traceparent injection for distributed tracing, and redacted sensitive headers in logs. ✅ Battle-Tested Comprehensive CI with CodeQL security scanning, spell checking, multi-platform testing (Linux/Windows/macOS), and 80%+ test coverage.

---

📖 Usage Examples

# POST with JSON body
azd rest post https://management.azure.com/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.Storage/storageAccounts/{name}?api-version=2021-04-01 \
  --data '{"location":"eastus","kind":"StorageV2","sku":{"name":"Standard_LRS"}}'

# POST with body from file
azd rest post https://management.azure.com/.../storageAccounts/{name}?api-version=2021-04-01 \
  --data-file storage-account.json

# Key Vault secret
azd rest get https://myvault.vault.azure.net/secrets/mysecret?api-version=7.4

# Microsoft Graph
azd rest get https://graph.microsoft.com/v1.0/me

# Azure Resource Graph (KQL) query
azd rest graph "Resources | summarize count() by type"

# Azure Resource Graph query from a file
azd rest graph --query-file resources.kql

# Show the signed-in Azure identity (tenant, app, scopes, expiry)
azd rest whoami

# Decode a token you already have and print its claims
azd rest jwt "$(azd auth token --output json | jq -r .token)"

# Public API (no auth)
azd rest get https://api.github.com/repos/Azure/azure-dev --no-auth

# Preview the detected scope without sending a request
azd rest scope https://management.azure.com/subscriptions?api-version=2020-01-01

# Custom headers + save response
azd rest get https://management.azure.com/subscriptions?api-version=2020-01-01 \
  --header "Accept: application/json" --output-file subscriptions.json

# Save structured response metadata for scripts or audit logs
azd rest get https://management.azure.com/subscriptions?api-version=2020-01-01 \
  --metadata-file metadata.json
# Review the final request shape without sending it
azd rest delete https://management.azure.com/subscriptions/{sub}/resourceGroups/{rg}?api-version=2021-04-01 \
  --dry-run

# Table output (works with arrays and ARM value[] responses)
azd rest get https://management.azure.com/subscriptions?api-version=2020-01-01 --format table

# Newline-delimited JSON (one object per line) for piping to jq -c
azd rest get https://management.azure.com/subscriptions?api-version=2020-01-01 --format jsonl

# dotenv KEY=value lines to eval into your shell or feed a CI job / docker --env-file
azd rest get https://management.azure.com/subscriptions/$SUB?api-version=2022-12-01 --format dotenv

# Read a single field into a shell variable without piping through jq -r
name=$(azd rest get https://management.azure.com/subscriptions/$SUB?api-version=2022-12-01 --query displayName -r)

# Minify the response to one line, for example to append one record per call to a log
azd rest get https://management.azure.com/subscriptions?api-version=2020-01-01 -c >> audit.log

# Send a YAML request body (converted to JSON automatically)
azd rest put https://management.azure.com/subscriptions/{sub}/resourceGroups/{rg}?api-version=2021-04-01 \
  --data-file group.yaml --data-format yaml

# Pipe a generated JSON body from stdin
cat group.json | azd rest put https://management.azure.com/subscriptions/{sub}/resourceGroups/{rg}?api-version=2021-04-01 \
  --data-file -

# Flatten a response to dotted paths, then grep for one field
azd rest get https://management.azure.com/subscriptions/{sub}/resourceGroups/{rg}?api-version=2021-04-01 \
  --flatten

# Mask any sensitive-looking field (passwords, keys, tokens) before sharing a response
azd rest get https://myvault.vault.azure.net/secrets/mysecret?api-version=7.4 --redact-secrets
# Fail if a required response header is missing or has a different value
azd rest get https://management.azure.com/subscriptions?api-version=2020-01-01 \
  --expect-header "Content-Type=application/json"
# Remove noisy fields from the response (structural complement to --redact)
azd rest get https://management.azure.com/subscriptions/{sub}/resourceGroups?api-version=2021-04-01 \
  --omit value.*.properties.provisioningState

# Diagnose authentication issues
azd rest doctor

# Pace repeated requests during a quick latency check
azd rest get https://management.azure.com/subscriptions?api-version=2020-01-01 \
  --repeat 3 --repeat-delay 2s
# Show the effective configuration and AZD_REST_* env var mappings
azd rest config

# Exit non-zero (code 22) on an HTTP error so scripts and CI stop on failure
azd rest get https://management.azure.com/subscriptions/{sub}/resourceGroups/{rg}?api-version=2021-04-01 --fail

# Snapshot check: compare the response to a saved baseline and exit non-zero on drift
azd rest get https://management.azure.com/subscriptions/{sub}/resourceGroups/{rg}?api-version=2021-04-01 --diff baseline.json
# Treat an expected 404 as success while still failing other HTTP errors
azd rest get https://management.azure.com/subscriptions/{sub}/resourceGroups/{rg}?api-version=2021-04-01 \
  --fail --allow-status 404
# Validate the response against a JSON Schema and exit non-zero when it does not conform
azd rest get https://management.azure.com/subscriptions/{sub}/resourceGroups/{rg}?api-version=2021-04-01 --validate-schema schema.json
# Assert on the response body in CI: fail the step unless the resource is provisioned
azd rest get https://management.azure.com/subscriptions/{sub}/resourceGroups/{rg}?api-version=2021-04-01 \
  --expect "properties.provisioningState=Succeeded"

For the complete command and flag reference, see the CLI Reference on the website.

⚙️ Development

Prerequisites

• Go 1.26+
• Node.js 20+ and pnpm
• Azure Developer CLI

Build & Test

# Build
cd cli && mage build

# Test
cd cli && mage test

# Lint
cd cli && mage lint

# All (fmt → lint → test → build → install)
cd cli && mage

For detailed testing information, see TESTING.md.

🔐 Security

azd rest uses your Azure credentials to authenticate API requests. Only make requests to trusted endpoints, use HTTPS (default), and never use --insecure in production.

See the Security Architecture page for the full threat model, SSRF protections, and hardening details.

📚 Documentation

• Website — Full documentation and guided tour
• CLI Reference — Complete command and flag reference
• Security Architecture — Threat model and security hardening
• Troubleshooting — Common error scenarios and solutions
• CONTRIBUTING.md — Contribution guidelines

🔗 azd Extensions

azd rest is part of a suite of Azure Developer CLI extensions by Jon Gallant.

Extension	Description	Website
azd app	Run Azure apps locally with auto-dependencies, dashboard, and AI debugging	jongio.github.io/azd-app
azd copilot	AI-powered Azure development with 16 agents and 28 skills	jongio.github.io/azd-copilot
azd exec	Execute scripts with azd environment context and Key Vault integration	jongio.github.io/azd-exec
azd rest	Authenticated REST API calls with automatic scope detection	jongio.github.io/azd-rest

🌐 Extension Hub: jongio.github.io/azd-extensions — Browse all extensions, quick install, and registry info.

License

MIT — see LICENSE for details.