DEV Community

Cover image for How to Use Azure APIs?
Preecha
Preecha

Posted on

How to Use Azure APIs?

TL;DR

Azure APIs let you programmatically access Microsoft cloud services such as storage, compute, databases, and AI. Authenticate with Microsoft Entra ID (formerly Azure AD), request an access token, then call the relevant REST endpoint.

Try Apidog today

For testing and documentation, use Apidog to save API calls, validate responses against schemas, and share collections with your team.

Introduction

Microsoft Azure has more than 200 services, and each service exposes APIs. In practice, most applications only use a small subset—for example:

  • Azure Blob Storage for files
  • Azure Functions for serverless workloads
  • Azure OpenAI for LLM integrations

The challenge is that Azure documentation is large and distributed across services. Finding the correct endpoint, configuring authentication, and diagnosing 401 Unauthorized responses can take longer than writing the integration itself.

This guide focuses on the Azure APIs developers use most often. You will learn how to:

  • Configure Azure authentication
  • Call Storage, Compute, and AI APIs
  • Debug common Azure API errors
  • Test and document Azure integrations with Apidog

💡 Apidog can help you organize Azure API requests into collections, manage variables for subscriptions and environments, and validate responses before changes reach production.

The authentication problem—and how to solve it

Every Azure API call needs authentication. If the token, scope, permissions, or headers are wrong, the request fails before it reaches the service.

Image

Azure Active Directory / Microsoft Entra ID

Azure uses OAuth 2.0 for API authentication. Instead of sending a username and password with each request, your application sends an access token that represents its identity and permissions.

The client credentials flow looks like this:

  1. Register an application in Microsoft Entra ID.
  2. Create a client secret.
  3. Assign API permissions and Azure roles.
  4. Request an access token.
  5. Send the token using the Authorization: Bearer header.

Step 1: Register an application

In the Azure portal, go to:

Microsoft Entra ID → App registrations → New registration
Enter fullscreen mode Exit fullscreen mode

Give the application a name. For an internal application, select Accounts in this organizational directory only.

After registration, copy these values:

Application (client) ID: 12345678-1234-1234-1234-123456789abc
Directory (tenant) ID: 87654321-4321-4321-4321-cba987654321
Enter fullscreen mode Exit fullscreen mode

Store them as environment variables:

export AZURE_TENANT_ID="87654321-4321-4321-4321-cba987654321"
export AZURE_CLIENT_ID="12345678-1234-1234-1234-123456789abc"
Enter fullscreen mode Exit fullscreen mode

Step 2: Create a client secret

In the app registration, open:

Certificates & secrets → New client secret
Enter fullscreen mode Exit fullscreen mode

Copy the secret value immediately. Azure does not display it again after you leave the page.

Client secret: abc123~DEF456-ghi789
Enter fullscreen mode Exit fullscreen mode

Store it outside your source code:

export AZURE_CLIENT_SECRET="abc123~DEF456-ghi789"
Enter fullscreen mode Exit fullscreen mode

Step 3: Assign permissions

Go to:

API permissions → Add a permission
Enter fullscreen mode Exit fullscreen mode

Examples:

  • For Azure Storage, select Azure Storage → user_impersonation
  • For Azure Management APIs, select Azure Service Management → user_impersonation

API permissions alone may not be enough. Your app's service principal also needs Azure RBAC access to the target resource. Assign roles from the resource's Access control (IAM) page.

Step 4: Request an access token

Request a token from the Entra ID token endpoint. The scope must match the API you plan to call.

For Azure Storage:

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"
Enter fullscreen mode Exit fullscreen mode

Example response:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIs...",
  "expires_in": 3599,
  "token_type": "Bearer"
}
Enter fullscreen mode Exit fullscreen mode

For Azure Resource Manager APIs, request a management token instead:

scope=https://management.azure.com/.default
Enter fullscreen mode Exit fullscreen mode

Step 5: Use the token

Pass the access token as a Bearer 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"
Enter fullscreen mode Exit fullscreen mode

Use the Azure SDK in application code

For production applications, use Azure SDKs where possible. They handle token acquisition, token refresh, retries, and serialization.

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

// Uses Azure CLI login or environment variables automatically.
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)
}
Enter fullscreen mode Exit fullscreen mode

Raw HTTP requests are still useful for testing, troubleshooting, and API documentation. Save those requests in Apidog so your team can reproduce them.

Azure Storage APIs

Azure Storage includes:

  • Blob Storage: files, images, and backups
  • Queue Storage: message queues
  • Table Storage: NoSQL key-value data
  • 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
Enter fullscreen mode Exit fullscreen mode

Create a container 

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

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!
Enter fullscreen mode Exit fullscreen mode

Download a blob 

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

Test Storage requests with Apidog

Azure Storage requests depend on exact headers, especially x-ms-version and Authorization.

Create a reusable collection with variables such as:

storage_account
storage_token
container
blob_name
Enter fullscreen mode Exit fullscreen mode

Then define request URLs using variables:

https://{{storage_account}}.blob.core.windows.net/{{container}}/{{blob_name}}
Enter fullscreen mode Exit fullscreen mode

This lets you switch between development and production accounts without editing every request manually.

Azure Compute APIs

Azure Compute APIs manage virtual machines, containers, and serverless workloads.

Management operations use the Azure Resource Manager endpoint:

https://management.azure.com
Enter fullscreen mode Exit fullscreen mode

These requests require a token with the following scope:

https://management.azure.com/.default
Enter fullscreen mode Exit fullscreen mode

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}
Enter fullscreen mode Exit fullscreen mode

Trigger an HTTP function 

POST https://{app-name}.azurewebsites.net/api/{function-name}
Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode 
{
  "name": "Azure",
  "message": "Hello from API"
}
Enter fullscreen mode Exit fullscreen mode

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}
Enter fullscreen mode Exit fullscreen mode

Virtual Machines API

List virtual machines 

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

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}
Enter fullscreen mode Exit fullscreen mode

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}
Enter fullscreen mode Exit fullscreen mode

Azure AI Services APIs

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

Azure OpenAI API

Create a chat completion 

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
Enter fullscreen mode Exit fullscreen mode 
{
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "What is Azure?"
    }
  ],
  "max_tokens": 500
}
Enter fullscreen mode Exit fullscreen mode

List deployments 

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

Cognitive Services API

Text Analytics: sentiment analysis 

POST https://{resource-name}.cognitiveservices.azure.com/text/analytics/v3.1/sentiment
Ocp-Apim-Subscription-Key: {subscription-key}
Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode 
{
  "documents": [
    {
      "id": "1",
      "language": "en",
      "text": "I love Azure APIs. They work great!"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Computer Vision: analyze an 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]
Enter fullscreen mode Exit fullscreen mode

Testing Azure APIs with Apidog

Azure APIs often combine multiple base URLs, authentication mechanisms, API versions, and required headers. Organizing those requests in a shared collection makes them easier to test and maintain.

1. Create environments

Azure APIs use different endpoints:

  • management.azure.com for control-plane operations
  • {account}.blob.core.windows.net for Blob Storage
  • {resource}.openai.azure.com for Azure OpenAI

Create separate environments for development and production.

# Development
MANAGEMENT_TOKEN: eyJ0eXAiOiJKV1Qi...
STORAGE_ACCOUNT: devstorage
OPENAI_RESOURCE: dev-openai
Enter fullscreen mode Exit fullscreen mode 
# Production
MANAGEMENT_TOKEN: eyJ0eXAiOiJKV1Qi...
STORAGE_ACCOUNT: prodstorage
OPENAI_RESOURCE: prod-openai
Enter fullscreen mode Exit fullscreen mode

Use variables in requests:

GET https://{{storage_account}}.blob.core.windows.net/?comp=list
Authorization: Bearer {{storage_token}}
x-ms-version: 2023-01-03
Enter fullscreen mode Exit fullscreen mode

2. Refresh tokens before requests

Azure access tokens usually expire after one hour. Use a pre-request script to refresh a token only when needed:

const tokenExpiry = pm.environment.get('token_expiry')
const now = Date.now() / 1000

if (!tokenExpiry || now >= tokenExpiry) {
  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)
}
Enter fullscreen mode Exit fullscreen mode

For Storage requests, change the scope to:

https://storage.azure.com/.default
Enter fullscreen mode Exit fullscreen mode

3. Validate API responses

Add tests to verify that Azure responses have the expected format.

For example, validate a Blob Storage container list response:

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')
})
Enter fullscreen mode Exit fullscreen mode

Common errors and how to fix them

401 Unauthorized

Cause: The token is invalid, expired, or issued for the wrong audience.

Fix:

  • Check whether the token has expired. expires_in is typically 3600 seconds.
  • Verify the requested scope matches the target API.
  • Confirm that the app registration has the required API permissions.
  • Ensure the request includes Authorization: Bearer {token}.

403 Forbidden

Cause: The token is valid, but the identity does not have permission to access the resource.

Fix:

  1. Open the Azure resource in the Azure portal.
  2. Go to Access control (IAM).
  3. Add a role assignment for the application's service principal.
  4. Retry with a newly issued token if permissions were recently changed.

404 Not Found

Cause: The endpoint, resource name, resource group, or API version is incorrect.

Fix:

  • Verify resource names in the URL.
  • Confirm the resource exists in the expected subscription and resource group.
  • Check the API version query parameter.
  • Make sure you are calling the correct endpoint: Resource Manager versus a service-specific endpoint.

429 Too Many Requests

Cause: The request rate exceeded an Azure limit.

Fix:

  • Implement exponential backoff.
  • Inspect the x-ms-ratelimit-remaining header.
  • Batch requests where supported. 
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
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Alternatives and comparisons

Feature Azure APIs AWS APIs GCP APIs
Authentication Azure AD / Entra ID (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 authentication is more complex than AWS's signature-based approach, but it integrates closely with enterprise identity systems.

Real-world use cases

E-commerce platform

A Shopify alternative uses:

  • Azure Blob Storage for product images
  • Azure Functions for order-processing webhooks
  • Azure OpenAI for product descriptions

The team saves and tests API calls in Apidog before deploying integration changes.

Healthcare SaaS

A medical records system uses:

  • Azure Cosmos DB for patient data
  • Azure Functions for HL7 message processing
  • Azure Key Vault for secrets

API testing validates response schemas as part of the system's compliance workflow.

AI startup

An AI-agent platform uses:

  • Azure OpenAI for LLM calls
  • Azure Storage for training data
  • Azure Container Apps for deployment

The team uses Apidog to mock Azure API responses during local development.

Wrapping up

You now have the core workflow for working with Azure APIs:

  • Azure authentication uses OAuth 2.0 tokens from Microsoft Entra ID.
  • Storage APIs require the x-ms-version header and a valid Bearer token.
  • Compute management operations use the Azure Resource Manager endpoint.
  • AI services may use API keys or Entra ID tokens, depending on the service.
  • API collections, environments, scripts, and response tests make integrations easier to maintain.

Next steps:

  1. Register an application in Microsoft Entra ID.
  2. Create credentials and request a token with the client credentials flow.
  3. Make a Blob Storage request.
  4. Save it as a reusable Apidog request.
  5. Build a collection for every Azure API your project depends on.

FAQ

What is the difference between Azure AD and Microsoft Entra ID?

They are the same identity service. Microsoft renamed Azure Active Directory to Microsoft Entra ID in 2023. Azure AD remains common in older documentation and code.

How do I get an API key for Azure OpenAI?

In the Azure portal, go to:

Azure OpenAI → Your resource → Keys and Endpoint
Enter fullscreen mode Exit fullscreen mode

You will see two keys. Either key works. Regenerate keys periodically and avoid committing them to source control.

Unlike the public OpenAI API, Azure OpenAI requires an Azure subscription, an Azure OpenAI resource, and a deployed model.

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

management.azure.com is the Azure Resource Manager endpoint. Use it to create, update, or delete Azure resources, such as virtual machines and storage accounts.

Service-specific endpoints are used to work with those resources:

{account}.blob.core.windows.net
{resource}.openai.azure.com
Enter fullscreen mode Exit fullscreen mode

For example, use Resource Manager to create a storage account, then use the Blob Storage endpoint to upload a file. These endpoints require tokens scoped for the relevant service.

How long do Azure access tokens last?

Azure access tokens typically last one hour, or 3600 seconds. Use the expires_in field from the token response to determine when to refresh.

Do not request a new token for every API call. Cache the token and renew it shortly before expiration.

Can I use managed identities instead of client secrets?

Yes. Managed identities are recommended for production workloads running in Azure because they eliminate the need to store client secrets.

They work with Azure VMs, Functions, Container Apps, and AKS. For local development, use Azure CLI authentication with az login or environment variables containing client credentials.

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

Compare the raw requests, especially:

  • Authorization headers
  • API versions
  • Content types
  • Required Azure headers such as x-ms-version
  • Request body format

A client may add headers automatically that your application code does not send. Use request inspection in Apidog to compare the outgoing request.

How do I test Azure APIs locally without an Azure subscription?

You cannot fully test Azure-hosted resources without a subscription, but you can use local tools:

  • Azurite for Azure Storage
  • Azure Functions Core Tools for Functions
  • Apidog mocks for simulated Azure API responses

What is the best way to handle Azure API errors?

Azure returns detailed error JSON. Parse the error.code and error.message fields, then handle known error types explicitly.

Common codes include:

  • AuthenticationFailed: check the token and scope.
  • ResourceNotFound: check the resource name and endpoint.
  • OperationNotAllowed: check subscription limits or resource configuration.

Top comments (0)