JWT & RBAC Middleware - Agentium

The router examples require application-owned identityFromVerifiedClaims and authorizeOwnedResource functions. Resolve only verified credentials; atomically bind new sessions and deny unknown/foreign resources. See authenticated hosting. Authentication or role checks alone are insufficient.

Overview

Agentium provides built-in JWT authentication and RBAC middleware for the Express transport layer. Configure authentication, RBAC, and mandatory host identity/resource authorization together.

Quick Start

import { createAgentRouter } from "@agentium/transport";

const router = createAgentRouter({
  security: {
    mode: "authenticated",
    resolveIdentity: identityFromVerifiedClaims,
    authorizeResource: authorizeOwnedResource,
  },
  jwt: {
    secret: process.env.JWT_SECRET!,
    algorithm: "HS256",
  },
  rbac: {
    agentScopes: {
      "admin-agent": ["admin:*"],
    },
  },
  cors: true,
});

JWT Configuration

Option	Type	Default	Description
`secret`	`string`	required	JWT signing secret
`algorithm`	`string`	—	Algorithm (HS256, RS256, etc.)
`issuer`	`string`	—	Expected token issuer
`audience`	`string`	—	Expected token audience
`extractFrom`	`"header" \| "cookie"`	`"header"`	Where to find the token
`cookieName`	`string`	`"token"`	Cookie name (when extractFrom is “cookie”)

Requires: npm install jsonwebtoken

RBAC Configuration

Option	Type	Default	Description
`scopeField`	`string`	`"scopes"`	JWT payload field containing scopes
`defaultScopes`	`Record<string, string[]>`	Built-in map	Route-to-scope mapping
`agentScopes`	`Record<string, string[]>`	—	Per-agent scope requirements

Built-in Scope Map

Route	Required Scopes
`POST /agents/:name/run`	`agents:run`
`POST /agents/:name/stream`	`agents:run`
`GET /agents`	`agents:read`
`POST /teams/:name/run`	`teams:run`
`GET /teams`	`teams:read`
`POST /workflows/:name/run`	`workflows:run`
`GET/POST/DELETE /admin/*`	`admin:*`

Token Format

{
  "sub": "user-123",
  "scopes": ["agents:run", "agents:read", "teams:run"],
  "iat": 1700000000,
  "exp": 1700003600
}

Wildcard scopes do not bypass resource authorization. Unknown routes are denied until explicitly registered in the RBAC route map.