Learn
Start from an API key. End able to read any flow.
6 short lessons, about 40 minutes in all. They assume you have built things that call APIs, and nothing else: no OAuth, no JWTs, no specifications.
The lessons
In order. Each builds on the one before, and each ends with questions to check yourself.
- 1What does the API actually see?Say what an API can and cannot know about a request from an agent, and why an API key is not enough.
- 2What is a token?Read an access token, name the five checks an API runs before believing it, and say what a valid token still does not prove.
- 3How does an agent get a token for a user?Explain each hop of an OAuth sign-in: why the browser is involved, why a code comes back before a token, and what a refresh token is for.
- 4What if nobody is there to sign in?Decide whether an agent should act for a person or as itself, and say where an agent’s own identity comes from.
- 5What happens when the agent calls a tool that calls an API?Explain why a token should be exchanged at each hop and not passed along, and tell delegation from impersonation.
- 6What limits the damage when something goes wrong?Name the two failures every agent design has to plan for, and the controls that limit each.
How the lessons work
- One example all the way through. Alice, an agent, and a calendar API. Each lesson changes one thing about it.
- Plain words first. The specifications’ terms arrive after the idea they name, and each lesson ends with a table of them.
- A figure you can change. Most lessons have one. It shows a complete answer before you touch it, and a table beneath it covers every case, so nothing depends on clicking.
- Nothing to install. These lessons explain the model. They are not a tutorial for one product, and every page they point to says what it was checked against.
Where to go from here
After the lessons, or instead of them if you know this ground already.
Choose a flow for your agent
Six questions about your agent, in the words these lessons used. The answer is a short list of flows, with the reason for each.
Read a flow at full size
20 flows as step-by-step diagrams, with the HTTP on the wire. Start with authorization code with PKCE: it is lesson 3 with nothing left out.
See what changes where your agent runs
Hosted apps, Kubernetes, managed agent platforms, desktops and command lines, CI and sandboxes: where the first credential comes from in each.
Keep the whole model on one page
The same ideas as these lessons, compressed, with the caveats left in. Useful once you know the ground.