Agent Management

Every AI client that connects to the gateway must authenticate as a named agent. Agents have their own token budget, tool allowlist, and audit trail. This page covers creating agents and issuing the JWTs they use to authenticate.

How agent auth works

The gateway issues and validates its own JWTs — it is the authorization server for MCP clients. When an agent connects, it presents a Bearer token signed with the gateway’s signing key. The gateway validates the signature, looks up the agent config, and enforces that agent’s budget and allowlist.

This is separate from any authentication your downstream API uses. The gateway handles agent auth; your API’s own auth is handled when the gateway forwards the request.

Getting an admin token

All management API calls require an admin JWT as a Bearer token. How you get one depends on your environment.

Production

Configure a strong random API key in your gateway’s environment:


# Example — generate a suitable key
openssl rand -hex 32

Set it as an environment variable (or in your secrets manager):


Ithil__Admin__ApiKey=<your-generated-key>

Then exchange it for an admin JWT:


curl -s -X POST http://your-gateway/auth/admin/token \
  -H "Content-Type: application/json" \
  -d '{ "apiKey": "<your-generated-key>" }'


{
  "token": "eyJhbGci...",
  "expiresAt": "2026-08-04T12:00:00Z"
}

Admin JWTs are valid for 90 days by default (configurable via Ithil:Admin:TokenExpiryDays). Store the token in your secrets manager and rotate it before it expires.

If Ithil:Admin:ApiKey is not set, the endpoint returns 404. The endpoint only exists when you explicitly enable it.

Development

Use the local shortcut (only works from localhost, only in development mode):


curl http://localhost:5100/dev/admin-token

Copy the token value.

Create an agent


curl -s http://localhost:5100/management/agents \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "My Claude Agent",
    "dailyTokenBudget": 50000
  }'

The response includes the new agentId:


{
  "agentId": "agt_3f9a1c2b",
  "label": "My Claude Agent",
  "dailyTokenBudget": 50000,
  "isActive": true
}

Optional fields

Field	Type	Description
`allowedTools`	`string[]`	Restrict the agent to specific tool names. Omit to allow all tools.
`scopes`	`string[]`	Reserved for future use.

Issue a token

With the agentId from above, issue a signed JWT:


curl -s -X POST http://localhost:5100/management/agents/agt_3f9a1c2b/token \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "expiresInDays": 30 }'


{
  "token": "eyJhbGci...",
  "expiresAt": "2026-06-05T12:00:00Z"
}

The token value is what goes into the MCP client config. Omit the request body to accept the default 30-day expiry.

Tokens are long-lived by design — 30 days means the agent keeps working without daily intervention. Issue a new token before the current one expires and update the client config.

Put the token in your MCP client

See Connecting AI Clients for how to add the token to Claude Desktop, Codex CLI, or any other MCP-compatible client.

Manage existing agents

List all agents


curl http://localhost:5100/management/agents \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

Get a single agent


curl http://localhost:5100/management/agents/agt_3f9a1c2b \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

Update an agent


curl -X PUT http://localhost:5100/management/agents/agt_3f9a1c2b \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "dailyTokenBudget": 100000, "isActive": true }'

Deactivate an agent

Set isActive: false. Existing tokens for that agent will be rejected immediately — no need to wait for them to expire.


curl -X PUT http://localhost:5100/management/agents/agt_3f9a1c2b \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "isActive": false }'

Delete an agent


curl -X DELETE http://localhost:5100/management/agents/agt_3f9a1c2b \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

Check and reset a budget


# Check remaining budget
curl http://localhost:5100/management/agents/agt_3f9a1c2b/budget \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"
 
# Reset the budget (e.g. after a billing period)
curl -X DELETE http://localhost:5100/management/agents/agt_3f9a1c2b/budget \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"