OpenAPI 3.1.0Apache-2.0raw.githubusercontent.com2026-08-14153188998.6 KB

4296a42a693e

Agents

Claim Agent

Claim ownership of a self-registered agent using its claim token.

Authenticated by the platform bearer token but requires no agent permission — the single-use claim token minted at /register is the proof, so the registering human (even a plain member) can take ownership. Sets owner_id to the caller; the existing scoping + approve paths then apply.

Restricted to USER actors: Agent.owner_id is a FK to users.id, so only a human can own an agent. The require_actor_type gate rejects a non-user actor (agent/service-account/toolkit) at the boundary with a 403; AgentService.claim re-checks the same invariant as defense-in-depth.

allow_expired_password=True is intentional (matching GET /agents/{id}): claiming is an onboarding step a brand-new user may hit before they have rotated a temporary password, so a must-change-password state must not block it. The claim only sets ownership — it grants no scopes and cannot act as the agent — so allowing it under an expired password is low-risk.

post/agents/{agent_id}:claim

Path parameters

agent_idstring required

Request body

tokenstring required

Response

Successful Response

approved_atstring date-time nullable
approved_bystring nullable
created_atstring date-time required
denial_reasonstring nullable
denied_bystring nullable
descriptionstring nullable
has_api_keyboolean
idstring required
namestring required
owner_idstring nullable
parent_agent_idstring nullable
registered_bystring required
statusstring required