Endpoints reference: Microsoft Entra SDK for Agent ID HTTP API

This document provides complete reference for the HTTP endpoints exposed by the Microsoft Entra SDK for AgentID.

API specification

OpenAPI specification: Available at /openapi/v1.json (development environment) and in the repository: https://github.com/AzureAD/microsoft-identity-web/blob/master/src/Microsoft.Identity.Web.Sidecar/OpenAPI/Microsoft.Identity.Web.Sidecar.json

Use it to:

• Generate client code
• Validate requests
• Discover available endpoints

Endpoint overview

Authentication

All token acquisition and validation endpoints require a bearer token in the Authorization header unless explicitly marked unauthenticated:

GET /AuthorizationHeader/Graph
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

Tokens are validated against configured Microsoft Entra ID settings (tenant, audience, issuer, scopes if enabled).

/Validate

Validates the inbound bearer token and returns its claims.

Request

GET /Validate HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

Successful response (200)

{
  "protocol": "Bearer",
  "token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "claims": {
    "aud": "api://your-api-id",
    "iss": "https://sts.windows.net/tenant-id/",
    "iat": 1234567890,
    "nbf": 1234567890,
    "exp": 1234571490,
    "acr": "1",
    "appid": "client-id",
    "appidacr": "1",
    "idp": "https://sts.windows.net/tenant-id/",
    "oid": "user-object-id",
    "tid": "tenant-id",
    "scp": "access_as_user",
    "sub": "subject",
    "ver": "1.0"
  }
}

Error examples

// 400 Bad Request - No token
{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "No token found"
}

// 401 Unauthorized - Invalid token
{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Unauthorized",
  "status": 401
}

/AuthorizationHeader/{serviceName}

Acquires an access token for the configured downstream API and returns it as an authorization header value. If a user bearer token is provided inbound, OBO (delegated) is used; otherwise app context patterns apply (if enabled).

Path parameter

• serviceName – Name of the downstream API in configuration

Query parameters

Standard overrides

Agent Identity

Rules:

• AgentUsername or AgentUserId require AgentIdentity (user agent).
• AgentUsername and AgentUserId are mutually exclusive.
• AgentIdentity alone = autonomous agent.
• AgentIdentity + user inbound token = delegated agent.

Examples

Basic request:

GET /AuthorizationHeader/Graph HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

GET /AuthorizationHeader/Graph?optionsOverride.RequestAppToken=true HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

GET /AuthorizationHeader/Graph?AgentIdentity=agent-id HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

Response

{
  "authorizationHeader": "Bearer eyJ0eXAiOiJKV1QiLCJhbGc..."
}

PoP/SHR response:

{
  "authorizationHeader": "PoP eyJ0eXAiOiJhdCtqd3QiLCJhbGc..."
}

/AuthorizationHeaderUnauthenticated/{serviceName}

Same behavior and parameters as /AuthorizationHeader/{serviceName} but no inbound user token is expected. Used for app-only or autonomous/agent identity acquisition without a user context. Avoids the overhead of validating a user token.

Request

GET /AuthorizationHeaderUnauthenticated/Graph HTTP/1.1

Response

{
  "authorizationHeader": "Bearer eyJ0eXAiOiJKV1QiLCJhbGc..."
}

/DownstreamApi/{serviceName}

Acquires an access token and performs an HTTP request to the downstream API. Returns status code, headers, and body from the downstream response. Supports user OBO, app-only, or agent identity patterns.

Path parameter

• serviceName – Configured downstream API name.

Additional query parameters (in addition to /AuthorizationHeader parameters)

Request body forwarding

Body is passed through unchanged:

POST /DownstreamApi/Graph?optionsOverride.RelativePath=me/messages HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...
Content-Type: application/json

{ 
  "subject": "Hello", 
   "body": { "contentType": "Text", "content": "Hello world" } 
}

Response

{
  "statusCode": 200,
  "headers": {
    "content-type": "application/json"
  },
  "content": "{\"@odata.context\":\"...\",\"displayName\":\"...\"}"
}

Errors mirror /AuthorizationHeader plus downstream API error status codes.

/DownstreamApiUnauthenticated/{serviceName}

Same as /DownstreamApi/{serviceName} but no inbound user token is validated. Use for app-only or autonomous agent operations.

/healthz

Basic health probe endpoint.

Response

Healthy (200):

HTTP/1.1 200 OK

Unhealthy (503):

HTTP/1.1 503 Service Unavailable

/openapi/v1.json

Returns OpenAPI 3.0 specification (development environment only). Use to:

• Generate client code
• Validate requests
• Discover endpoints

Common error patterns

Bad request (400)

Missing service name:

// 400 Bad Request - Missing service name
{ "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Bad Request", "status": 400, "detail": "Service name is required" }

// 400 Bad Request - Invalid agent combination
{ "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Bad Request", "status": 400, "detail": "AgentUsername and AgentUserId are mutually exclusive" }

// 401 Unauthorized - Invalid token
{ "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Unauthorized", "status": 401 }

// 403 Forbidden - Missing scope
{ "type": "https://tools.ietf.org/html/rfc7231#section-6.5.3", "title": "Forbidden", "status": 403, "detail": "The scope 'access_as_user' is required" }

// 404 Not Found - Service not configured
{ "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found", "status": 404, "detail": "Downstream API 'UnknownService' not configured" }

// 500 Internal Server Error - Token acquisition failure
{ "type": "https://tools.ietf.org/html/rfc7231#section-6.6.1", "title": "Internal Server Error", "status": 500, "detail": "Failed to acquire token for downstream API" }

MSAL error example

{ "type": "https://tools.ietf.org/html/rfc7231#section-6.6.1", "title": "Internal Server Error", "status": 500, "detail": "MSAL.NetCore.invalid_grant: AADSTS50076: Due to a configuration change ...", "extensions": { "errorCode": "invalid_grant", "correlationId": "..." } }

Complete override reference

optionsOverride.Scopes=<scope>     # Repeatable
optionsOverride.RequestAppToken=<true|false>
optionsOverride.BaseUrl=<url>
optionsOverride.RelativePath=<path>
optionsOverride.HttpMethod=<method>
optionsOverride.AcquireTokenOptions.Tenant=<tenant-id>
optionsOverride.AcquireTokenOptions.AuthenticationScheme=<scheme>
optionsOverride.AcquireTokenOptions.CorrelationId=<guid>
optionsOverride.AcquireTokenOptions.PopPublicKey=<base64-key>
optionsOverride.AcquireTokenOptions.PopClaims=<json>
optionsOverride.CustomHeader.<Name>=<value>

AgentIdentity=<agent-client-id>
AgentUsername=<user-upn>            # Requires AgentIdentity
AgentUserId=<user-object-id>        # Requires AgentIdentity

Examples of override

Override scopes:

GET /AuthorizationHeader/Graph?optionsOverride.Scopes=User.Read&optionsOverride.Scopes=Mail.Read HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

Rate limiting

The Microsoft Entra SDK for Agent ID itself does not impose rate limits. Effective limits come from:

1. Microsoft Entra ID token service throttling (shouldn't happen as the SDK caches token)
2. Downstream API limits
3. Token cache efficiency (reduces acquisition volume)

Best practices

1. Prefer configuration over ad-hoc overrides.
2. Keep service names static and declarative.
3. Implement retry policies for transient failures (HTTP 500/503).
4. Validate agent parameters before calling.
5. Log correlation IDs for tracing across services.
6. Monitor token acquisition latency and error rates.
7. Use health probes in orchestration platforms.

Related content

• Configuration Reference
• Agent Identities
• Validate Authorization Header
• Call Downstream API