How to Use Azure APIs?

TL;DR

Azure APIs provide programmatic access to Microsoft cloud services—storage, compute, databases, AI, and more. Authenticate using Azure Active Directory (Entra ID), obtain an access token, and call REST endpoints. To efficiently test and document your API calls, use Apidog to save requests, validate responses, and collaborate with your team.

Try Apidog today

Introduction

Microsoft Azure offers 200+ services, each with its own API. Most developers interact with a handful—Blob Storage for files, Functions for serverless, or OpenAI for LLMs.

Azure’s documentation is vast and fragmented, making it time-consuming to locate endpoints, configure authentication, or resolve 401 Unauthorized errors.

This guide targets the most-used Azure APIs. Learn actionable authentication patterns, avoid common pitfalls, and test your Azure integrations before deploying.

💡 Tip: Apidog streamlines Azure API design, testing, and documentation. Save collections, manage environments, validate schemas, and catch configuration errors early.

Test your Azure APIs with Apidog—free.

By the end, you’ll be able to:

• Set up Azure authentication (the most common stumbling block)
• Call Azure Storage, Compute, and AI APIs with working examples
• Debug frequent Azure API errors
• Test and document Azure integrations with Apidog

The authentication problem (and how to solve it)

Every Azure API call requires authentication. If this fails, nothing else works—this is where most devs get stuck.

Azure Active Directory / Microsoft Entra ID

Azure uses OAuth 2.0: you send an access token, not a username/password.

Authentication flow:

1. Register an application in Azure AD (Entra ID)
2. Obtain a client ID and client secret
3. Request an access token from Azure’s token endpoint
4. Attach that token to your API calls

Step 1: Register an application

• Go to Azure Portal → Microsoft Entra ID → App registrations → New registration.
• Name your app, select “Accounts in this organizational directory only” for internal apps, and register.

You’ll get:

• Application (client) ID: 12345678-1234-1234-1234-123456789abc
• Directory (tenant) ID: 87654321-4321-4321-4321-cba987654321

Step 2: Create a client secret

• In your app registration, go to Certificates & secrets → New client secret.
• Copy the secret value immediately.

Example:

• Client secret: abc123~DEF456-ghi789

Step 3: Assign permissions

• Go to API permissions → Add a permission.
• For Storage: “Azure Storage” → “user_impersonation”.
• For Management APIs: “Azure Service Management” → “user_impersonation”.

Step 4: Get an access token

curl -X POST "https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id={client-id}" \
  -d "client_secret={client-secret}" \
  -d "scope=https://storage.azure.com/.default" \
  -d "grant_type=client_credentials"

Response:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIs...",
  "expires_in": 3599,
  "token_type": "Bearer"
}

Step 5: Use the token

curl -X GET "https://youraccount.blob.core.windows.net/container?restype=container&comp=list" \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIs..." \
  -H "x-ms-version: 2023-01-03"

Using Azure SDK instead of raw HTTP

In production, use the Azure SDK—it handles token refresh, retries, and serialization.

import { DefaultAzureCredential } from '@azure/identity'
import { BlobServiceClient } from '@azure/storage-blob'

const credential = new DefaultAzureCredential()
const blobServiceClient = new BlobServiceClient(
  'https://youraccount.blob.core.windows.net',
  credential
)

// List containers
for await (const container of blobServiceClient.listContainers()) {
  console.log(container.name)
}

For testing, debugging, and documentation, understanding raw HTTP is essential. That’s where Apidog excels.

Azure Storage APIs

Azure Storage is widely used and includes:

• Blob Storage: Files, images, backups
• Queue Storage: Message queues
• Table Storage: NoSQL key-value store
• File Storage: SMB file shares

Blob Storage API

List containers:

GET https://{account}.blob.core.windows.net/?comp=list
Authorization: Bearer {token}
x-ms-version: 2023-01-03

Create a container:

PUT https://{account}.blob.core.windows.net/{container}?restype=container
Authorization: Bearer {token}
x-ms-version: 2023-01-03

Upload a blob:

PUT https://{account}.blob.core.windows.net/{container}/{blob}
Authorization: Bearer {token}
x-ms-version: 2023-01-03
Content-Type: text/plain

Hello, Azure Blob Storage!

Download a blob:

GET https://{account}.blob.core.windows.net/{container}/{blob}
Authorization: Bearer {token}
x-ms-version: 2023-01-03

Testing with Apidog

Azure Storage APIs require specific headers (x-ms-version, correct auth). With Apidog:

1. Save reusable requests for each operation.
2. Use environment variables for account names and tokens.
3. Validate responses against schemas.

Design and test Azure Storage APIs faster with Apidog.

Azure Compute APIs

Azure Compute manages VMs, containers, and serverless functions.

Azure Functions API

List functions in a function app:

GET https://management.azure.com/subscriptions/{subscription-id}/resourceGroups/{rg}/providers/Microsoft.Web/sites/{app-name}/functions?api-version=2023-01-01
Authorization: Bearer {management-token}

Trigger a function (HTTP trigger):

POST https://{app-name}.azurewebsites.net/api/{function-name}
Content-Type: application/json

{
  "name": "Azure",
  "message": "Hello from API"
}

Get function keys:

POST https://management.azure.com/subscriptions/{subscription-id}/resourceGroups/{rg}/providers/Microsoft.Web/sites/{app-name}/functions/{function-name}/listKeys?api-version=2023-01-01
Authorization: Bearer {management-token}

Virtual Machines API

List VMs:

GET https://management.azure.com/subscriptions/{subscription-id}/providers/Microsoft.Compute/virtualMachines?api-version=2023-07-01
Authorization: Bearer {management-token}

Start a VM:

POST https://management.azure.com/subscriptions/{subscription-id}/resourceGroups/{rg}/providers/Microsoft.Compute/virtualMachines/{vm-name}/start?api-version=2023-07-01
Authorization: Bearer {management-token}

Stop a VM:

POST https://management.azure.com/subscriptions/{subscription-id}/resourceGroups/{rg}/providers/Microsoft.Compute/virtualMachines/{vm-name}/powerOff?api-version=2023-07-01
Authorization: Bearer {management-token}

Azure AI Services APIs

Azure provides OpenAI models and cognitive services for vision, speech, and language.

Azure OpenAI API

Get completions:

POST https://{resource-name}.openai.azure.com/openai/deployments/{deployment-id}/chat/completions?api-version=2024-02-15-preview
api-key: {your-api-key}
Content-Type: application/json

{
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is Azure?"}
  ],
  "max_tokens": 500
}

List deployments:

GET https://{resource-name}.openai.azure.com/openai/deployments?api-version=2024-02-15-preview
api-key: {your-api-key}

Cognitive Services API

Text Analytics - Sentiment:

POST https://{resource-name}.cognitiveservices.azure.com/text/analytics/v3.1/sentiment
Ocp-Apim-Subscription-Key: {subscription-key}
Content-Type: application/json

{
  "documents": [
    {
      "id": "1",
      "language": "en",
      "text": "I love Azure APIs. They work great!"
    }
  ]
}

Computer Vision - Analyze Image:

POST https://{resource-name}.cognitiveservices.azure.com/vision/v3.2/analyze?visualFeatures=Description,Tags
Ocp-Apim-Subscription-Key: {subscription-key}
Content-Type: application/octet-stream

[binary image data]

Testing Azure APIs with Apidog

Azure APIs often require complex authentication and precise headers. Manual testing with curl is error-prone. Apidog makes this easier:

1. Environment management

Azure APIs span multiple endpoints:

• management.azure.com for resource management
• {account}.blob.core.windows.net for storage
• {resource}.openai.azure.com for AI

Create environments in Apidog:

# Development
MANAGEMENT_TOKEN: eyJ0eXAiOiJKV1Qi...
STORAGE_ACCOUNT: devstorage
OPENAI_RESOURCE: dev-openai

# Production
MANAGEMENT_TOKEN: eyJ0eXAiOiJKV1Qi...
STORAGE_ACCOUNT: prodstorage
OPENAI_RESOURCE: prod-openai

2. Pre-request scripts for token refresh

Azure tokens expire every hour. Add a pre-request script:

// Check if token is expired
const tokenExpiry = pm.environment.get('token_expiry')
const now = Date.now() / 1000

if (!tokenExpiry || now >= tokenExpiry) {
  // Request new token
  const response = await pm.sendRequest({
    url: 'https://login.microsoftonline.com/' + pm.environment.get('tenant_id') + '/oauth2/v2.0/token',
    method: 'POST',
    header: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: {
      mode: 'urlencoded',
      urlencoded: [
        { key: 'client_id', value: pm.environment.get('client_id') },
        { key: 'client_secret', value: pm.environment.get('client_secret') },
        { key: 'scope', value: 'https://management.azure.com/.default' },
        { key: 'grant_type', value: 'client_credentials' }
      ]
    }
  })

  const data = response.json()
  pm.environment.set('management_token', data.access_token)
  pm.environment.set('token_expiry', now + data.expires_in)
}

3. Response validation

Validate Azure responses against expected schemas:

// Test that blob list returns expected structure
pm.test('Response has containers', () => {
  const xml = pm.response.text()
  pm.expect(xml).to.include('<Containers>')
  pm.expect(xml).to.include('<Container>')
})

pm.test('Response is valid XML', () => {
  pm.response.to.be.ok
  pm.response.to.have.header('Content-Type', 'application/xml')
})

Accelerate Azure API testing with Apidog—free.

Common errors and how to fix them

401 Unauthorized

Cause: Invalid or expired token.

Fix:

1. Check token expiration (expires_in is usually 3600 seconds)
2. Ensure scope matches the API
3. Confirm app registration has correct permissions

403 Forbidden

Cause: Token valid but lacks permissions.

Fix:

1. In Azure Portal, go to the resource
2. Check Access control (IAM)
3. Add a role assignment for your app’s service principal

404 Not Found

Cause: Wrong endpoint or resource doesn’t exist.

Fix:

1. Verify resource name in the URL
2. Check API version in the query string
3. Ensure resource exists in the correct group

429 Too Many Requests

Cause: Rate limits exceeded.

Fix:

1. Implement exponential backoff
2. Monitor x-ms-ratelimit-remaining header
3. Batch requests where possible

Example exponential backoff in TypeScript:

async function callWithRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn()
    } catch (error) {
      if (error.statusCode === 429) {
        const delay = Math.pow(2, i) * 1000
        await new Promise(resolve => setTimeout(resolve, delay))
      } else {
        throw error
      }
    }
  }
}

Alternatives and comparisons

Feature	Azure APIs	AWS APIs	GCP APIs
Authentication	Azure AD (OAuth 2.0)	IAM (Sig v4)	OAuth 2.0
SDK quality	Excellent	Excellent	Excellent
Documentation	Comprehensive but scattered	Service-specific	Service-specific
Rate limiting	Per-subscription	Per-service	Per-project
Free tier	12 months + always free	12 months	Always free + credits

Azure’s authentication is more complex than AWS’s SigV4 but offers better enterprise identity integration.

Real-world use cases

• E-commerce platform: Uses Azure Blob Storage for images, Functions for orders, and OpenAI for product descriptions. All API calls are tested in Apidog before deployment.
• Healthcare SaaS: Uses Cosmos DB for records, Functions for HL7 processing, and Key Vault for secrets. API schemas are validated for HIPAA compliance.
• AI startup: Uses Azure OpenAI for LLMs, Storage for training data, and Container Apps for deployments. Mocks Azure APIs with Apidog during local development.

Wrapping up

Key takeaways:

• Azure authentication uses OAuth 2.0 via Azure AD (Entra ID)
• Storage APIs require x-ms-version and Bearer tokens
• Compute APIs use the Resource Manager endpoint
• AI services use API keys or AAD tokens
• Test and document everything with Apidog

Next steps:

1. Register an app in Azure AD and obtain credentials
2. Request an access token using client credentials flow
3. Make your first Azure Storage API call
4. Save that call in Apidog as a reusable request
5. Build a collection of your project’s Azure API calls

Test Azure APIs with Apidog—free.

FAQ

What’s the difference between Azure AD and Microsoft Entra ID?

They’re the same. Microsoft rebranded Azure Active Directory to Microsoft Entra ID in 2023. Both names appear in docs; use Entra ID for new projects.

How do I get an API key for Azure OpenAI?

Azure Portal → Azure OpenAI → your resource → Keys and Endpoint. There are two keys; both work. Regenerate periodically. Unlike OpenAI’s public API, Azure OpenAI requires a subscription and resource deployment.

What’s the difference between management.azure.com and service-specific endpoints?

management.azure.com (Azure Resource Manager) is for resource CRUD (create VM, delete storage). Service-specific endpoints ({account}.blob.core.windows.net, {resource}.openai.azure.com) are for using those resources. You need different tokens for each.

How long do Azure access tokens last?

Typically 1 hour (3600 seconds). Use the expires_in field. Don’t request a new token for every call—refresh only when needed.

Can I use managed identities instead of client secrets?

Yes, and you should for Azure-hosted workloads. Managed identities remove the need for secret storage. They work with VMs, Functions, Container Apps, and AKS. For local development, use Azure CLI (az login) or environment variables.

Why does my API call work in Postman but fail in code?

Check headers. Azure APIs are case-sensitive. Postman may add headers automatically. Compare raw requests between tools using Fiddler or Apidog’s request inspector.

How do I test Azure APIs locally without a subscription?

You can’t fully test without a subscription, but you can use local emulators:

• Azurite for Storage
• Azure Functions Core Tools for Functions
• Use Apidog to mock Azure API responses

What’s the best way to handle Azure API errors?

Azure returns error JSON. Parse the error.code and error.message fields. Common codes:

• AuthenticationFailed – check your token
• ResourceNotFound – check the resource name
• OperationNotAllowed – check subscription limits