Hosted agent token service reference in Microsoft Foundry

The hosted-agent token service in Microsoft Foundry lets you obtain access tokens to call downstream services from your agent code. You can use these tokens to authenticate requests without storing credentials in your application.

This article describes how to obtain tokens, which identity the service selects for each request, and the REST request and response contract. A separate section covers blueprint exchange for autopilot agents.

For the relationship between agent identities, agent blueprints, and downstream permissions, see Agent identity concepts.

Obtain tokens through Azure Identity

The Azure Identity SDKs obtain tokens for the agent identity through ManagedIdentityCredential. Despite its name, this credential accesses the hosted-agent token service; it doesn't give your code access to the project managed identity. The runtime provides the endpoint configuration that the credential uses.

The following examples use DefaultAzureCredential for simplicity. Its credential chain includes ManagedIdentityCredential, which accesses the hosted-agent token service. For production, use an explicit credential or a ChainedTokenCredential with only the credential types your application needs.

Run these examples in a hosted-agent container. They request an Azure Storage access token. To call a different service, replace the scope with that service's resource identifier followed by /.default.

Python
C#

Install the Azure Identity client library for Python:

python -m pip install azure-identity

Request a token:

import sys

from azure.core.exceptions import ClientAuthenticationError
from azure.identity import DefaultAzureCredential

with DefaultAzureCredential() as credential:
    try:
        token = credential.get_token("https://storage.azure.com/.default")
    except ClientAuthenticationError:
        print("Agent identity token acquisition failed.", file=sys.stderr)
        raise

    print(f"Token expires at Unix timestamp {token.expires_on}.")

Use token.token when authenticating a request to the target service. The example prints only the expiration time, not the token.

To select an identity explicitly, use DefaultAzureCredential(managed_identity_client_id="<agent-identity-client-id>"). Use an identity allowed by the identity selection rules, not the project managed identity.

Reference: DefaultAzureCredential, ManagedIdentityCredential, ChainedTokenCredential, AccessToken.

Add the Azure Identity client library for .NET to your project:

dotnet add package Azure.Identity

If your project already obtains the credential types through Azure.Core, follow the library's package migration guidance instead of adding a duplicate reference.

Request a token:

using System;
using System.Threading;
using Azure.Core;
using Azure.Identity;

var credential = new DefaultAzureCredential();

try
{
    AccessToken token = await credential.GetTokenAsync(
        new TokenRequestContext(["https://storage.azure.com/.default"]),
        CancellationToken.None);

    Console.WriteLine($"Token expires at {token.ExpiresOn:O}.");
}
catch (AuthenticationFailedException)
{
    Console.Error.WriteLine("Agent identity token acquisition failed.");
    throw;
}

Use token.Token when authenticating a request to the target service. The example prints only the expiration time, not the token.

To select an identity explicitly, set DefaultAzureCredentialOptions.ManagedIdentityClientId when constructing DefaultAzureCredential. Use an identity allowed by the identity selection rules, not the project managed identity.

Reference: DefaultAzureCredential, DefaultAzureCredentialOptions.ManagedIdentityClientId, ManagedIdentityCredential, ChainedTokenCredential, TokenRequestContext, AccessToken.

Identity selection

By default, the token service uses the agent identity of the current instance. The agent identity associated with the agent definition represents the default instance.

General hosted agents use only the default instance, so the current and default instance identities are the same. For autopilot agents, the current instance's identity is distinct from the default instance's identity.

Selection by client ID

Use the SDK's client ID setting to select an identity, or leave it unspecified to use the current instance's identity. The following rules apply to resource-token requests:

Client ID selection	Identity/token returned	Notes
Not specified	Current instance identity token	For general hosted agents, the current instance is the default instance.
Current instance identity's client ID	Current instance identity token	This is equivalent to leaving the client ID unspecified.
Default instance identity's client ID	Default instance identity token	For general hosted agents, this is the same identity as the current instance. Explicit selection matters when they differ.
Any other client ID	Rejected¹	The caller can't select an arbitrary identity.

¹ The agent blueprint ID associated with the current instance is an exception to this rejection rule. See Blueprint exchange for autopilot agents.

REST request and response

For direct REST requests, the client_id parameter corresponds to the SDK's client ID setting. The same identity selection rules apply.

The hosted runtime provides two environment variables:

Environment variable	Description
`IDENTITY_ENDPOINT`	The URL of the token service endpoint available inside the hosted-agent container.
`IDENTITY_HEADER`	The value to send in the `X-IDENTITY-HEADER` request header.

Read these values from the environment rather than hardcoding the endpoint or header. Don't log the header value or returned access tokens.

Request

Send an HTTP GET request to the URL in IDENTITY_ENDPOINT with the following parameters.

Parameter	Location	Required	Description
`resource`	Query	Yes	The Microsoft Entra resource URI of the target service, such as `https://storage.azure.com`. Use the resource URI, not an SDK scope ending in `/.default`.
`api-version`	Query	Yes	The token API version. Use `2019-08-01`.
`X-IDENTITY-HEADER`	Header	Yes	The value of the `IDENTITY_HEADER` environment variable.
`client_id`	Query	No	The client ID of the identity to select. If omitted, the service uses the current instance's identity. See Selection by client ID.

URL-encode query parameter values. Identity selection accepts only a client ID, not a principal ID, object ID, or Azure resource ID.

The following request illustrates token acquisition for Azure Storage without an explicit client ID. Replace the path, host, and header placeholders with values from the runtime environment.

GET <path-from-IDENTITY_ENDPOINT>?resource=https%3A%2F%2Fstorage.azure.com&api-version=2019-08-01 HTTP/1.1
Host: <host-and-port-from-IDENTITY_ENDPOINT>
X-IDENTITY-HEADER: <value-of-IDENTITY_HEADER>

To select an identity explicitly, append &client_id=<agent-identity-client-id> to the query string.

Response

A successful request returns HTTP 200 OK with a JSON response. The following example uses placeholders instead of an actual access token or identity identifier.

{
  "access_token": "<access-token>",
  "expires_on": "<unix-timestamp>",
  "resource": "https://storage.azure.com",
  "token_type": "Bearer",
  "client_id": "<selected-identity-client-id>"
}

Field	Description
`access_token`	The access token to use when authenticating to the target service.
`expires_on`	The token expiration time, expressed as seconds since the Unix epoch.
`resource`	The resource URI for which the token was requested.
`token_type`	The token type, `Bearer`.
`client_id`	The client ID of the identity represented by the token.

Send the access token to the target service in the Authorization header as Bearer <access-token>. A valid token doesn't grant permissions by itself; the target service still checks the selected identity's access.

Errors

Unsupported identity selections are rejected rather than returning a token for an arbitrary identity.

Check the HTTP response status before reading access_token as a successful result. For a failed request, check the following conditions.

Condition	What to check
Missing or invalid request parameters	Supply the target service's resource URI and `api-version=2019-08-01`. URL-encode query parameter values.
Missing or incorrect authentication header	Send `X-IDENTITY-HEADER` with the value supplied by the runtime in `IDENTITY_HEADER`.
Unsupported identity selection	Omit `client_id` to use the current instance's identity, or select an identity allowed by the identity selection rules.
Token acquisition failure	Inspect the error details returned by the token service. Don't treat an error response as an access token.

A downstream service rejecting a successfully acquired token is a separate failure. Check the token's target resource and the selected identity's permissions on that service.

Permissions and token handling

Identity selection doesn't grant access to a downstream resource. The selected identity needs the permissions required by that resource. For agent identity role assignments, see Assign permissions to the agent identity.

Don't log access tokens or include them in diagnostic output.

Blueprint exchange for autopilot agents

Autopilot agents use a separate blueprint exchange token for their flow to impersonate an agent user account. General hosted agents don't need this exchange token.

For autopilot agents, Microsoft 365 supplies the agent identity for the current instance. The hosted runtime uses sessions to isolate that instance's identity context.

When you select the agent blueprint ID associated with the current instance as the client ID, the service returns a blueprint exchange token. This token is bound to the current instance's agent identity. The blueprint can only be used for that agent identity. This token isn't a normal downstream resource access token.

Feedback

Was this page helpful?

Last updated on 2026-10-23