Track 03 · Agents & toolsLesson 05 of 12
Tools with scoped, auditable access
Least-privilege credentials per tool, so the security review says yes.
- Lesson library · reference
- 40 min read
- 60 min hands-on
- Pro
What you'll be able to do
01- Choose between building a custom tool and using a connector platform, and explain the token-custody and review implications of each.
- Explain the four common auth patterns at the tool (API keys, delegated user tokens, on-behalf-of token exchange, service accounts) and pick one per tool based on who is acting and what must be attributable.
- Design least privilege at three levels (scopes, resource constraints, parameter constraints) and say where each is enforced.
- Implement a tool-execution wrapper that enforces per-agent and per-tenant allow-lists, scopes, parameter limits, rate limits and approval binding, injects secrets without exposing them to the model, redacts logs and writes an audit record per call.
- Defend the design in a security review, answering "who did this, on whose authority, with what access?" for any tool call.
Before you start
- Designing tools a model can use well: read/write separation and "do not ask the model for what the system knows".
- MCP: connecting agents to the customer's systems: MCP's authorisation model for HTTP servers and the ban on token passthrough.
- Agent or workflow? Choosing the autonomy level: the determinism boundary.
- Retrieval that respects who can see what: the same principle applied at the retrieval layer.
- Working knowledge of OAuth 2.0 roles (client, resource server, authorisation server) and scopes.
The short version
Every tool call is an action taken by some identity with some set of permissions. Scoped access means that identity and those permissions are explicit, minimal and enforced outside the model. At the tool you choose how the call authenticates: a static API key, the user's own delegated OAuth token, a narrower token obtained on the user's behalf through token exchange, or a service account acting on its own authority. You then restrict what that credential can do at three levels: scopes (coarse permissions in the token), resource constraints (which records) and parameter constraints (which values, such as an allowed template or a maximum amount). An execution wrapper enforces per-agent and per-tenant allow-lists, checks scopes and parameters, rate-limits, requires approval for gated writes, injects secrets from a secret manager so the model never sees them, and writes an audit record naming the agent, the user it acted for and the decision. The model proposes a call; your code decides whether it runs and with what credential.
Key takeaways:
- The model never holds credentials. Secrets are injected at execution time and never appear in prompts, tool arguments, results or logs.
- Identity and tenant come from the authenticated session, never from model output.
- Enforce allow-lists at execution, not only by hiding tools from the prompt.
- Delegated or exchanged user tokens keep the agent inside the user's permissions; service accounts need compensating controls and explicit attribution.
- Every tool call, allowed or denied, produces an audit record.
Pro lesson
The rest of this lesson is in Pro.
The mental model, worked example, field note, failure table, exercise and self-check, with the voice tutor.
- Every stage and specialisation, in full
- Every lab and every role project
- Halden weeks 2–10, on your record
- Every drill, live in the playground
- All solutions, plus the server judge
- Lab Assistant and every Teach with AI