Skip to content

Repeated initAgent registration incorrectly requires AGENTS_UPDATE #263

Description

@josjeon

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

  1. Configure a valid non-admin API key.
  2. Register a new agent with POST /api/v1/agents/initAgent; the request returns
    200.
  3. 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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions