# Byok 401 Debug Expert

> Diagnose the silent BYOK 401 that Foundry hosted agents emit when "Foundry User" RBAC is assigned at PROJECT scope but missing at the underlying CognitiveServices ACCOUNT scope. Encodes the exact fix command.

- **Type:** Skill
- **Install:** `agentstack add skill-aiappsgbb-awesome-gbb-byok-401-debug-expert`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [aiappsgbb](https://agentstack.voostack.com/s/aiappsgbb)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [aiappsgbb](https://github.com/aiappsgbb)
- **Source:** https://github.com/aiappsgbb/awesome-gbb/tree/main/skills/azure-sre-agent/references/plugins/gbb-foundry/skills/byok_401_debug_expert

## Install

```sh
agentstack add skill-aiappsgbb-awesome-gbb-byok-401-debug-expert
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# byok_401_debug_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
   ```

2. **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
   ```

3. **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.

4. **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
   ```

5. **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.

6. **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](https://github.com/aiappsgbb)
- **Source:** [aiappsgbb/awesome-gbb](https://github.com/aiappsgbb/awesome-gbb)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-aiappsgbb-awesome-gbb-byok-401-debug-expert
- Seller: https://agentstack.voostack.com/s/aiappsgbb
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.