Key Types & Scopes

Master Key (g_master_)

• One per user. Creating a new one revokes the previous (and cascade-revokes all agent keys).

• Full access to all endpoints and all agents owned by the user.

Agent Key (g_agent_)

• One per agent. Tied to a single agent by agent_id.

• Cannot access other agents (returns 403).

• Access controlled by scopes assigned at creation time.

Scopes

Scope	Description	Default
agent:read	View agent details and status	Always included
agent:manage	Start, stop, pause, reload. Manage sessions and archives	No
channels	Manage Telegram pairing (list, approve, revoke, reject)	No
files	Upload files to the agent	No
chat	Send messages to the agent via API	No

A master key implicitly has all scopes.