Summary
POST /api/v1/agents/initAgent authorizes the route with AGENTS_CREATE, but an
existing registration also requires AGENTS_UPDATE for overwrite, force-replace,
or a changed strict-mode payload.
The built-in header provider permits AGENTS_CREATE for authenticated callers and
reserves AGENTS_UPDATE for admins. Because both SDKs default registration to
overwrite mode, a non-admin agent can register successfully on its first startup
and then receive 403 on its next startup.
Motivation
The intended authorization boundary established in #61 and #62 keeps
initAgent available to non-admin runtime callers while reserving explicit agent
management and control-plane mutations for admins. The secondary authorization
added with namespace scoping in #214 makes repeated registration cross that
boundary. This also conflicts with overwrite being the SDK default introduced by
#40.
Current behavior
- Configure a valid non-admin API key.
- Register a new agent with
POST /api/v1/agents/initAgent; the request returns
200.
- Send an overwrite registration for the same agent name; the request returns
403 because the server requests AGENTS_UPDATE.
Expected behavior
Initial and repeated initAgent registration should use the same registration
authorization operation and namespace. A non-admin registration caller should be
able to refresh its metadata, steps, and evaluators through initAgent.
Explicit management endpoints—including policy association, direct control
attachment, and PATCH /agents/{name}—should continue to require
AGENTS_UPDATE and remain admin-only under the built-in header provider.
Proposed solution
Keep the route-level AGENTS_CREATE authorization for the entire initAgent
upsert and remove its secondary AGENTS_UPDATE checks. Add regression coverage
for changed, no-op, strict, and force-replace registrations, plus a public HTTP
test proving that a non-admin key can register and refresh while management
endpoints remain denied.
Risk
A caller allowed to register agents can update an existing same-name registration
within its namespace, including force-replacing corrupted registration data. This
matches the endpoint's documented initialize-or-update contract; per-agent
ownership is a separate authorization concern.
Summary
POST /api/v1/agents/initAgentauthorizes the route withAGENTS_CREATE, but anexisting registration also requires
AGENTS_UPDATEfor overwrite, force-replace,or a changed strict-mode payload.
The built-in header provider permits
AGENTS_CREATEfor authenticated callers andreserves
AGENTS_UPDATEfor admins. Because both SDKs default registration tooverwrite mode, a non-admin agent can register successfully on its first startup
and then receive
403on its next startup.Motivation
The intended authorization boundary established in #61 and #62 keeps
initAgentavailable to non-admin runtime callers while reserving explicit agentmanagement and control-plane mutations for admins. The secondary authorization
added with namespace scoping in #214 makes repeated registration cross that
boundary. This also conflicts with overwrite being the SDK default introduced by
#40.
Current behavior
POST /api/v1/agents/initAgent; the request returns200.403because the server requestsAGENTS_UPDATE.Expected behavior
Initial and repeated
initAgentregistration should use the same registrationauthorization operation and namespace. A non-admin registration caller should be
able to refresh its metadata, steps, and evaluators through
initAgent.Explicit management endpoints—including policy association, direct control
attachment, and
PATCH /agents/{name}—should continue to requireAGENTS_UPDATEand remain admin-only under the built-in header provider.Proposed solution
Keep the route-level
AGENTS_CREATEauthorization for the entireinitAgentupsert and remove its secondary
AGENTS_UPDATEchecks. Add regression coveragefor changed, no-op, strict, and force-replace registrations, plus a public HTTP
test proving that a non-admin key can register and refresh while management
endpoints remain denied.
Risk
A caller allowed to register agents can update an existing same-name registration
within its namespace, including force-replacing corrupted registration data. This
matches the endpoint's documented initialize-or-update contract; per-agent
ownership is a separate authorization concern.