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.

​
Map each route to one of three choices

For every route, pick exactly one:
ChoiceMeaningUse for
scope: <name>Token must carry this scopeAnything that touches data or actions
public: trueNo token requiredHealth checks, status, open metadata
skip: trueReturns 404 — invisible to agentsInternal/admin routes agents shouldn’t see
platform_id: 4f8e9c1d-2b4f-5e6a-7b8c-9d0e1f2a3b4c
version: 1
routes:
  - method: GET
    path: /health
    public: true
  - method: GET
    path: /api/v1/items
    scope: items:read
  - method: GET
    path: /api/v1/items/{item_id}
    scope: items:read
  - method: POST
    path: /api/v1/items
    scope: items:write

​
Path parameters

Use brace syntax for variable segments. The middleware matches the shape, not the value: 
  - method: GET
    path: /api/v1/items/{item_id}
    scope: items:read
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.

​
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.