Endpoint and authentication

The endpoint URL

The Endpoint URL is a base. AMC adds a trailing slash if it's missing and resolves every path relative to it, so an endpoint of https://invoices.contoso.com/amc gets https://invoices.contoso.com/amc/health, https://invoices.contoso.com/amc/runs, and so on.

• •It must be an absolute http or https URL. Use https anywhere but local testing; managed identity requires it.
• •Path segments don't change these URLs. They only form the resource id AMC sends as orchestratorWorkflowId. See the resource id.
• •The health check does not follow redirects. Serve /health directly.

API key

In key mode AMC presents the key in an api-key header on every call, including /health. It never sends the key as Authorization: Bearer, and never sends both headers.

POST /amc/runs HTTP/1.1
Host: invoices.contoso.com
api-key: <your-agent-api-key>
Content-Type: application/json; charset=utf-8

import os

from fastapi import Depends, FastAPI, Header, HTTPException

API_KEY = os.environ["AGENT_API_KEY"]


def check_key(api_key: str | None = Header(default=None, alias="api-key")) -> None:
    if api_key != API_KEY:
        raise HTTPException(status_code=401, detail="unauthorized")


app = FastAPI(dependencies=[Depends(check_key)])

• •Return 401 or 403 for a bad key. At registration that shows as Access not granted, which tells the person the endpoint is up and the key is wrong.
• •AMC stores the key in Key Vault, never returns it, and deletes it when the registration is deactivated.
• •To rotate, update the registration with the new key. AMC checks the new key against /health before it replaces the stored one, so accept both keys while you switch.

Managed identity

In managed-identity mode AMC requests a Microsoft Entra token from its own managed identity for the Resource scope you register, and presents it as Authorization: Bearer <token>. Your service validates it like any Entra access token issued for your app.

1. 1Create an app registration for your endpoint and give it an application ID URI, for example api://invoice-summarizer.
2. 2Have your AMC administrator approve your host and that audience for the installation (below).
3. 3Register as a Tenant Admin (or Super Admin) with Managed Identity (same tenant) and Resource scope set to api://invoice-summarizer/.default.
4. 4In your service, accept tokens for that audience from AMC's identity, and reject everything else with 401.

AMC's identity is shared by the whole installation, so it refuses to send a token anywhere it wasn't told to. A custom-endpoint registration with managed identity must pass every rule, or registration fails before anything is stored:

The approvals live in one installation setting, Registration:SelfHostedManagedIdentityTargets, in the form host=audience[,audience...][;host=...]. A host entry admits that host and its subdomains, never look-alikes. Empty, the default, means managed identity is off for custom endpoints.

agents.contoso.com=api://invoice-summarizer/.default;tools.contoso.com=api://tool-a/.default,api://tool-b/.default

Tenancy

• •AMC is multi-tenant. Each AMC tenant registers your endpoint separately, and each registration has its own credential and its own runs.
• •AMC sends no tenant identifier on calls to your endpoint. A managed-identity token is the same for every tenant on an installation, so it can't tell them apart.
• •If one endpoint serves several AMC tenants, give each registration its own API key and map key to tenant on your side. Never let one tenant's run id resolve for another.
• •Your agent's own outbound credentials (to your model provider, to the systems it reads) are yours to manage. AMC never sees them.