Skip to main content
The middleware enforces exactly what’s in your mudraid_scopes.yaml. Designing that file well is the main work of integrating as a platform — and it’s a design task, not just config. This guide walks through it.

​
Start from the permissions, not the routes

Before mapping routes, decide what an agent should be able to do on your API. Those are your scopes. Keep them coarse enough to be meaningful and fine enough to be useful:
  • items:read, items:write
  • orders:read, orders:write, orders:cancel
Use resource:action. The names are visible to agent owners when they request access, so make them self-explanatory. A scope reaches an agent’s token only through an approved grant: the grant names your platform’s resource and the scopes the agent’s OAuth client may use, and a token carries, in its scope claim, the scopes the client requested — every one of which the grant must cover.

​
Map each route to one of three choices

For every route, pick exactly one:

​
Path parameters

Use brace syntax for variable segments. The middleware matches the shape, not the value:
So /api/v1/items/42 and /api/v1/items/abc both match this one rule.

​
Routes with no rule return 404

A route you don’t list behaves exactly like skip: true — it returns 404. A hidden route and a non-existent route are indistinguishable to a caller, on purpose, so agents can’t probe your surface. The flip side: if you forget to list a real route, agents will get 404s on it. Listing routes is mandatory, not optional.

​
Scopes are flat — no implicit hierarchy

items:write does not grant items:read. If a route needs both, require both and grant both. There’s no “higher” scope that quietly unlocks “lower” ones. It’s slightly more verbose, and it eliminates a whole class of accidental over-permissioning.

​
Getting the file

Define scopes and route mappings in the portal, then download mudraid_scopes.yaml there. A deployment can also fetch it with the platform’s own API key from GET /api/v1/platforms/{platform_id}/scopes.yaml (send X-Api-Key and X-Api-Secret; the key needs platform:verify). Both return the same bytes, with routes ordered most-specific first — the middleware matches first-match-wins.

​
MCP tools

If you map MCP tools to scopes in the portal, the file lists them under a separate tools: key. The V1 middleware ignores that block: tool calls are authorized by the signed action bundle and a live /decide call, through V2 mode.

​
Common mistakes to avoid

  • Forgetting a route — it 404s. List every route an agent should reach.
  • Assuming hierarchy — grant each scope explicitly.
  • One mega-scope — api:all defeats the point. Scope by resource and action.
  • Hand-editing in production — the portal is the source of truth; see the lifecycle guide.