Auth and identity done right
Already assigning Foundry User at project scope? Skip to the next lesson.
Most Azure agent failures are not the model going wrong. They are the cloud saying no. This is the single most valuable lesson in the course, because almost everyone hits this and the error message does not explain itself.
What a 403 means
A 403 Forbidden means Azure knows who you are and has decided you are not allowed. It is not a bug and retrying will not help. Something needs permission it does not have.
Two ideas sort out most of it.
Keys versus identity. An API key is a password in your code. It works instantly and it is a liability: it gets copied into chat messages, committed to Git, and never changed. The alternative is DefaultAzureCredential, which uses who you are already signed in as. No secret in the code. Real teams disable keys entirely, and then key-based code stops working overnight.
Control plane versus data plane. Managing a resource and using it are different permissions. Creating the AI service is the control plane. Actually running an agent is the data plane. Being an administrator of something does not automatically let you use it, which is why Contributor, the role that sounds like it should do everything, does not.
Task, role, scope
| What you are doing | Role you need | Where to assign it |
|---|---|---|
| Create or run an agent | Foundry User | On the project |
| Deploy models, manage the resource | Contributor or Owner | Resource or subscription |
| Run locally or in CI without keys | DefaultAzureCredential | Your identity needs the role above |
Foundry User and Azure AI User are the same role. Microsoft renamed it partway through, so you will see both.
Scope means where a permission applies. Foundry User on the whole subscription but not on the project is not enough. Assign it on the project.
Wait before you panic
Permission changes take a few minutes to spread across Azure. Assign a role, get a 403 straight away, and it may already be correct. Wait five minutes and try again before you start rewriting code that was never broken.
What to write
- Keep
AZURE_DEPLOYMENTasagents-chat - Set
AZURE_CREDENTIALtoDefaultAzureCredential - Set
AZURE_ROLEtoFoundry UserandAZURE_SCOPEtoproject - Call
chat(messages, deployment=AZURE_DEPLOYMENT)in the loop
Keys, Contributor and subscription-only scope are all rejected here with the real error text.
The point
Running an agent is a data-plane action. You need Foundry User on the project, and Contributor will not save you.
Break it on purpose
Set the role to Contributor at subscription scope and run. That 403 is the most common message in this whole ecosystem. Read it once here on purpose.
Check yourself
Answer out loud first. Reading the answer without trying is where the learning leaks out.
1. Why does Contributor fail for agent create?
2. Which scope must Foundry User use?
3. What should you try before debugging code after a role change?