Named agents with per-tool scopes

ModGate gives every AI agent a named identity — not just an API key. Each agent gets a specific set of tools it can call, and nothing else. One-click revocation kills access instantly.

Why this matters

Without ModGate

Any agent with a token can call any tool on your MCP server.

With scopes only

Agents are limited to broad categories (read, write) — not specific tools.

With agent identity

Agent "billing-bot" can call get_invoice but not delete_customer. Enforced cryptographically.

1. Create a named agent

You can create agents from the dashboard under Agent Identities → Create agent, or via the API:

POST https://api.modgate.io/agents/{tenantId}
X-ModGate-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "name": "billing-bot",
  "description": "Handles invoice lookups for the billing workflow",
  "delegatedBy": "[email protected]",
  "scopes": [
    { "serverId": "srv_abc123", "tool": "get_invoice" },
    { "serverId": "srv_abc123", "tool": "list_invoices" },
    { "serverId": "srv_abc123", "tool": "get_customer" }
  ],
  "expiresAt": "2026-12-31T00:00:00Z"
}

# Response:
{
  "id": "agent_xyz789...",
  "name": "billing-bot",
  "tenantId": "org_...",
  "scopes": [...],
  "delegatedBy": "[email protected]",
  "createdAt": "2026-06-30T00:00:00Z",
  "expiresAt": "2026-12-31T00:00:00Z",
  "active": true
}

Two more fields you'll use once you're past the basics: canDelegate lets this agent spawn scoped sub-agents (see Cross-agent delegation below), and continuousAuth tunes its reverification window and rate-anomaly threshold — see Continuous authorization.

2. Scope policies

Each scope in the scopes array specifies which server and which tool the agent is allowed to call. Both fields support a wildcard:

Scope	Meaning
{ "serverId": "srv_abc", "tool": "get_invoice" }	Call only get_invoice on server srv_abc
{ "serverId": "srv_abc", "tool": "*" }	Call any tool on server srv_abc
{ "serverId": "*", "tool": "get_invoice" }	Call get_invoice on any registered server
{ "serverId": "", "tool": "" }	Full access — all tools, all servers (use carefully)

Wildcard scopes (*) should only be used for trusted internal agents. For customer-facing or third-party agents, always specify explicit tool names.

3. Update agent scopes

You can update an agent's scope policies at any time. Changes take effect on the next tool call.

PATCH https://api.modgate.io/agents/{tenantId}/{agentId}/scopes
X-ModGate-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "scopes": [
    { "serverId": "srv_abc123", "tool": "get_invoice" },
    { "serverId": "srv_abc123", "tool": "list_invoices" },
    { "serverId": "srv_abc123", "tool": "create_invoice" }
  ]
}

4. List agents

GET https://api.modgate.io/agents/{tenantId}
X-ModGate-API-Key: YOUR_API_KEY

# Response:
{
  "agents": [
    {
      "id": "agent_xyz789",
      "name": "billing-bot",
      "active": true,
      "scopes": [...],
      "createdAt": "2026-06-30T00:00:00Z"
    }
  ],
  "total": 1
}

5. Revoke an agent

One-click revocation from the dashboard, or via API. Revoked agents are rejected on their very next request — every proxied tool call re-checks the agent's live status against its current stored state, not just its token's signature or expiry.

DELETE https://api.modgate.io/agents/{tenantId}/{agentId}
X-ModGate-API-Key: YOUR_API_KEY

# Response:
{
  "revoked": true,
  "agentId": "agent_xyz789",
  "tenantId": "org_..."
}

Revocation marks the agent as inactive and is permanent — you cannot reactivate a revoked agent. Create a new agent identity if you need to restore access. This preserves a clean audit trail.

Need to invalidate every outstanding token for an agent right now, without waiting for the agent to make another call? See force-reauth, the admin kill switch.

6. What gets logged

Every tool call by every named agent is logged in the audit log with full context:

{
  "eventType": "tool.called",
  "outcome": "success",          // or "denied" if scope check failed
  "agentId": "agent_xyz789",
  "agentName": "billing-bot",
  "tenantId": "org_...",
  "serverId": "srv_abc123",
  "tool": "get_invoice",
  "durationMs": 142,
  "timestamp": "2026-06-30T12:34:56Z",
  "ip": "203.0.113.0"
}

Denied tool calls — where an agent tries to call a tool outside its scope — are also logged with "outcome": "denied" and a reason. Your audit trail captures both successful access and attempted violations.

7. Cross-agent delegation (xAA)

Agents that orchestrate other agents — a planner spawning worker sub-agents, for example — can be marked as delegation-capable. A delegation-capable agent mints scoped tokens for its sub-agents directly, without those sub-agents ever going through the authorization code flow themselves.

POST https://api.modgate.io/agents/{tenantId}
X-ModGate-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "name": "research-orchestrator",
  "scopes": [{ "serverId": "srv_abc123", "tool": "*" }],
  "canDelegate": true,
  "maxDelegationDepth": 3
}

Once created, the orchestrator calls /oauth/delegate with its own access token to mint a token for a sub-agent. Every hop is recorded in a cryptographically verifiable chain — [root, ..., parent, this_agent] — so you can trace any tool call back through every agent that authorized it.

A sub-agent can only ever receive scopes the orchestrator already holds — delegation narrows permissions, never widens them. Depth is capped by maxDelegationDepth to prevent unbounded chains. See OAuth 2.1 setup for the full /oauth/delegate request and response reference.

Revoke the orchestrator and the entire chain beneath it breaks immediately — every sub-agent token becomes unusable on its next call, whether or not it has expired yet.

Next steps

Quickstart →

OAuth 2.1 setup →

Full auth flow, PKCE, and Dynamic Client Registration

Continuous authorization →

Live revocation, kill switch, rate limits

Questions? We answer personally.

[email protected] →