Agents

Claim Agent

Changed on

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 (an agent) 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 permissions and cannot act as the agent — so allowing it under an expired password is low-risk.

post/agents/{agent_id}:claim

Request

  • Base URL: / (relative, and the document was published on a file host, not at the API’s origin)
  • URL: /agents/{agent_id}:claim
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL /authorize, token URL /oauth/token)

Path parameters

agent_idstring required

ID of the agent.

Example:agnt_6968b3984d1c238dbe7e2e29

Request body

tokenstring required

Single-use claim token returned when the agent self-registered.

Example request

{
  "token": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
}

Response

Successful Response

approved_atstring date-time nullable

When the agent was approved (RFC 3339); null if not approved.

approved_bystring nullable

ID of the user who approved the agent; null if not approved.

created_atstring date-time required

When the agent was created (RFC 3339).

denial_reasonstring nullable

Reason given when the agent was denied; null if not denied.

denied_bystring nullable

ID of the actor that denied the agent; null if not denied.

descriptionstring nullable

Free-text description of the agent; null if not set.

has_api_keyboolean

Whether the agent currently has an active API key.

idstring required

Unique ID of the agent.

namestring required

Human-readable name of the agent.

owner_idstring nullable

ID of the user who owns the agent; null for an unclaimed self-registration.

parent_agent_idstring nullable

ID of the parent agent; null when the agent has no parent.

registered_bystring required

ID of the actor that registered the agent, or self for a self-registration.

statusstring required

Lifecycle status of the agent: pending, active, rejected, disabled or archived.

Example response

{
  "approved_at": "2026-01-15T09:45:00Z",
  "approved_by": "usr_6968b3987ee4c3ec0b4ee3b9",
  "created_at": "2026-01-15T09:30:00Z",
  "denial_reason": "Requested permissions exceed the agent's stated purpose.",
  "denied_by": "usr_6968b3987ee4c3ec0b4ee3b9",
  "description": "Reconciles Stripe invoices against the ledger every night.",
  "has_api_key": true,
  "id": "agnt_6968b3984d1c238dbe7e2e29",
  "name": "invoice-reconciler",
  "owner_id": "usr_6968b3987ee4c3ec0b4ee3b9",
  "parent_agent_id": "agnt_6968b3984d1c238dbe7e2e29",
  "registered_by": "usr_6968b3987ee4c3ec0b4ee3b9",
  "status": "active"
}

Changes