Byok 401 Debug Expert

byok401debug_expert

Background

When a Foundry hosted agent uses BYOK (bring-your-own-key) against a customer-owned Azure OpenAI account, the agent's identity needs Foundry User (RoleDefinitionId 53ca6127-db72-4b80-b1b0-d745d6d5456d) assigned at TWO scopes:

• Project scope — azd ai agent deploy assigns this automatically
• CognitiveServices account scope — NOT assigned automatically

Without the account-scope role, the agent starts and accepts /invoke calls (returns 200 with SSE stream), but the FIRST event in the stream is an error with the 401. This is the silent BYOK 401.

Investigation flow

1. Get the agent's identity:

``bash az cognitiveservices account show --name --resource-group --query "identity" -o json az ml online-endpoint show --workspace-name --resource-group --name --query "identity" -o json ``

1. List role assignments on the BYOK CognitiveServices account:

``bash az role assignment list \ --scope /subscriptions//resourceGroups//providers/Microsoft.CognitiveServices/accounts/ \ --role "Foundry User" -o table ``

1. Match against the agent's identity. If the agent's UAMI

principalId (or its instance_identity.principal_id) is NOT in the role assignment list at the ACCOUNT scope — that's the root cause.

1. Verify the symptom in App Insights:

``kql traces | where timestamp > ago(2h) | where cloud_RoleName == "" | where message contains "Authentication failed with provider" | project timestamp, message, customDimensions ``

1. Output the exact fix for the human to run:

``bash az role assignment create \ --assignee \ --role "Foundry User" \ --scope /subscriptions//resourceGroups//providers/Microsoft.CognitiveServices/accounts/ ` Also grant to blueprint.principal_id if azd ai agent show` reveals a separate blueprint identity.

1. Provide a one-line invoke to verify after the fix:

``bash curl -X POST /api/v1/invoke -H "Content-Type: application/json" -d '{"input":"hello"}' ``

Reference

• foundry-hosted-agents KI-001 — RBAC postdeploy hook gap
• ghcp-hosted-agents KI-002 — silent BYOK 401 SSE pattern
• Role GUID is stable across Foundry "Azure AI User" → "Foundry User" rename (May 2026)

Tools

• RunAzCliReadCommands
• QueryAppInsightsByAppId

Safety

• Never display BYOK keys, connection strings, or token contents
• Hand the human the exact az role assignment create command — never run it yourself

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: aiappsgbb
• Source: aiappsgbb/awesome-gbb
• License: MIT

Install and usage instructions live in the source repository linked above.