Microsoft Entra Agent ID
Developer

Call a custom API as a user with the Auth SDK sidecar

In brief

The new guide explains how an agent uses the Auth SDK sidecar and OAuth On-Behalf-Of flow to obtain a downstream authorization header and call a custom API for a signed-in user. It covers delegated scopes, consent, sidecar configuration, security guidance, and Python and JavaScript examples.

What Entra admins need to know

Administrators implementing this scenario should configure delegated access and consent, and ensure the downstream API validates the token, scope, and user authorization.

This editorial summary was generated by AI from the documentation changes. Verify important details in the full Microsoft Learn article.

Documentation change

The comparison below shows only the changed extract. Use the full-page view for complete context.

new file mode 100644

title: Call a custom API as a user with the Auth SDK sidecar description: Use the Auth SDK sidecar and On-Behalf-Of flow to call a custom API for the signed-in user. titleSuffix: Microsoft Entra Agent ID ms.topic: how-to ms.date: 11/06/2026 ai-usage: ai-assisted ms.reviewer: dastrock

Call a custom API as a user with the Auth SDK sidecar

Use the OAuth On-Behalf-Of (OBO) flow when an upstream client calls an agent for a signed-in user and the agent calls a custom API for that user.

The agent first validates the inbound access token, then forwards the same authorization header to the sidecar. The sidecar uses its configured credential to get a downstream authorization header for that user.

Prerequisites

  • Completion of Authenticate users with the Auth SDK sidecar, including consent for the upstream client to call the agent.
  • A delegated scope exposed by the downstream API.
  • Consent for the agent to call that API for the user.

Configure access

  1. Expose a delegated scope on the custom API.
  2. Declare the scope in the blueprint's requiredResourceAccess.
  3. Obtain user or administrator consent for the agent identity to use that scope.
  4. Configure the API and scope in the sidecar.

Configure the sidecar

Add a delegated profile for the custom API:

{
  "DownstreamApis": {
    "custom-api": {
      "BaseUrl": "https://api.contoso.com/",
      "Scopes": [
        "api://<custom-api-client-id>/<delegated-scope>"
      ]
    }
  }
}

Use the shared client ID and keep identity overrides disabled as described in Configure the Auth SDK sidecar.

Get a downstream token

Forward the token issued for the agent API:

GET /AuthorizationHeader/custom-api
Authorization: ******

Send the returned authorizationHeader to the custom API. The custom API must validate the token and enforce the required scope and user authorization.

Don't send the inbound token directly to the custom API. It is intended for the agent, not the downstream resource. Don't return or log either authorization header.

Call the sidecar and custom API

The following example forwards the inbound user authorization header to the sidecar, reads the downstream authorization header, and calls the custom API:

Python

import requests

SIDECAR_URL = "http://localhost:5000"

inbound_auth_header = "<authorization-header-from-agent-request>"

sidecar_response = requests.get(
    f"{SIDECAR_URL}/AuthorizationHeader/custom-api",
    headers={"Authorization": inbound_auth_header},
    timeout=5,
)

if sidecar_response.status_code in (401, 403):
    raise PermissionError("The sidecar rejected the user token or OBO request.")

sidecar_response.raise_for_status()
authorization_header = sidecar_response.json()["authorizationHeader"]

api_response = requests.get(
    "https://api.contoso.com/user-data",
    headers={"Authorization": authorization_header},
    timeout=10,
)
api_response.raise_for_status()
response_body = api_response.json()

JavaScript

const SIDECAR_URL = "http://localhost:5000";

const inboundAuthHeader = "<authorization-header-from-agent-request>";

const sidecarResponse = await fetch(
    `${SIDECAR_URL}/AuthorizationHeader/custom-api`,
    { headers: { Authorization: inboundAuthHeader } }
);

if (sidecarResponse.status === 401 || sidecarResponse.status === 403) {
    throw new Error("The sidecar rejected the user token or OBO request.");
}

if (!sidecarResponse.ok) {
    throw new Error(`Sidecar request failed with status ${sidecarResponse.status}.`);
}

const { authorizationHeader } = await sidecarResponse.json();

const apiResponse = await fetch("https://api.contoso.com/user-data", {
    headers: { Authorization: authorizationHeader },
});

if (!apiResponse.ok) {
    throw new Error(`API request failed with status ${apiResponse.status}.`);
}

const responseBody = await apiResponse.json();

Keep SIDECAR_URL on loopback in the shared network namespace. Replace the authorization-header placeholder with the complete Authorization header received by the agent. Process responseBody according to the custom API's response contract.

Treat the sidecar response as a credential. Don't log or return authorizationHeader.

Verify that the API enforces the delegated scope and the user's access. If OBO reports missing consent, check upstream access to the agent separately from downstream consent; the OBO exchange can't display a consent prompt.

Related content

Daily Entra.News

Get daily email updates

Get a concise summary of the latest Microsoft Entra updates delivered straight to your inbox.

Loading the secure signup form…