Azure AI Foundry

Use the models you deployed in Azure, with an API key or with no key at all through Microsoft Entra ID. Each deployment name becomes a model ID, so gpt-5-prod in Azure is gpt-5-prod in your requests.

Add Azure

1. Go to Model Providers → Add API Key and select Azure AI Foundry.

2. Set Base URL to your resource, not to one deployment:

   Your resource	Base URL
   Azure OpenAI	https://<resource-name>.openai.azure.com/openai
   A Foundry project with its own OpenAI endpoint	https://<project-name>.openai.azure.com/openai
   Microsoft Foundry v1	https://<resource-name>.services.ai.azure.com/openai/v1

3. Paste the resource's API key from the Azure Portal. Leave it empty if you use Entra ID.

4. Click Test & Create.

Your deployments show under Models. Clients call https://<archestra-host>/v1/azure with a virtual key, or with the Azure key as Authorization: Bearer.

One provider key covers the whole resource. Do not add a key for each deployment.

Sign In Without a Key

Let Archestra sign in to Azure as itself, so no Azure key is stored anywhere. It uses Azure's DefaultAzureCredential: a workload identity, a managed identity, a service principal, or your local Azure CLI sign-in.

1. Set ARCHESTRA_AZURE_OPENAI_ENTRA_ID_ENABLED=true.
2. Give that identity a role on the Azure resource: Cognitive Services OpenAI User for Azure OpenAI, or Cognitive Services User for Foundry Models.
3. Add Azure as above, with the API key empty.

To try the flow on your laptop first, see the keyless example.

On AKS

Use Microsoft Entra Workload ID with a user-assigned managed identity. Turn on the OIDC issuer and workload identity, and create a federated credential for Archestra's service account:

az aks update \
  --resource-group "$AKS_RESOURCE_GROUP" \
  --name "$AKS_CLUSTER_NAME" \
  --enable-oidc-issuer \
  --enable-workload-identity

export AKS_OIDC_ISSUER="$(az aks show \
  --resource-group "$AKS_RESOURCE_GROUP" \
  --name "$AKS_CLUSTER_NAME" \
  --query oidcIssuerProfile.issuerUrl \
  --output tsv)"

az identity federated-credential create \
  --resource-group "$IDENTITY_RESOURCE_GROUP" \
  --identity-name "$USER_ASSIGNED_IDENTITY_NAME" \
  --name archestra-platform \
  --issuer "$AKS_OIDC_ISSUER" \
  --subject "system:serviceaccount:$NAMESPACE:$SERVICE_ACCOUNT_NAME" \
  --audience api://AzureADTokenExchange

Then annotate the Helm service account and add the pod label required by the AKS workload identity webhook:

archestra:
  orchestrator:
    kubernetes:
      serviceAccount:
        name: archestra-platform
        annotations:
          azure.workload.identity/client-id: "<user-assigned-managed-identity-client-id>"
  podLabels:
    azure.workload.identity/use: "true"
  env:
    ARCHESTRA_AZURE_OPENAI_ENTRA_ID_ENABLED: "true"

Then set the identity and the pod label in your Helm values:

archestra:
  orchestrator:
    kubernetes:
      serviceAccount:
        name: archestra-platform
        annotations:
          azure.workload.identity/client-id: "<user-assigned-managed-identity-client-id>"
  podLabels:
    azure.workload.identity/use: "true"
  env:
    ARCHESTRA_AZURE_OPENAI_ENTRA_ID_ENABLED: "true"

The subject must match your Helm release's namespace and service account. See Microsoft's AKS Workload ID guide.

When It Does Not Work

What to Know

• Narrowest access: use a custom role with Microsoft.Resources/subscriptions/read, Microsoft.Resources/subscriptions/resources/read, Microsoft.CognitiveServices/accounts/read, and Microsoft.CognitiveServices/accounts/deployments/read.
• Discovery and requests on different endpoints: set inferenceBaseUrl on the provider key through the API. Archestra lists deployments from Base URL and sends every request to the inference URL.
• Grok on Azure works through a Foundry v1 URL, once the model is deployed.