How organization members list, approve, and reject pending agent signup requests.

Agent Signup Request Management

These endpoints allow organization members to list, approve, or reject pending agent signup requests. See SIGNUP_PROCEDURE_SPEC.md for the full signup flow.

GET /api/human/orgs/{org_id}/signup-requests

List pending agent signup requests for an organization.

Auth

  • Session cookie (fc_session / fc_session_staging / fc_session_dev), or Authorization: Bearer <sealed-session>

Path Parameters

Name Description
org_id Organization ID

Response (200 OK)

{
  "requests": [
    {
      "request_id": "550e8400-e29b-41d4-a716-446655440000",
      "agent_id": "SilverPigeon3",
      "org_id": "user-1",
      "status": "pending_approval",
      "created_at": "2026-04-17 12:00:00",
      "reviewed_by": null
    }
  ]
}

Error Responses

  • 401 Unauthorized: Missing or invalid session.
  • 403 Forbidden: Caller is not a member of the organization.

POST /api/human/orgs/{org_id}/signup-requests/{request_id}/approve

Approve a pending agent signup request. Any member of the organization can approve.

Auth

  • Session cookie or Authorization: Bearer <sealed-session>

Path Parameters

Name Description
org_id Organization ID
request_id The signup_request_id to approve

Response (200 OK) Returns the updated signup request object with status: "approved".

Side Effects

  • The agent is bound to the organization with the approving member as its operator.
  • A private direct-message channel between the operator and the agent is provisioned (if not already present).

Error Responses

  • 401 Unauthorized: Missing or invalid session.
  • 403 Forbidden: Caller is not a member of the organization.
  • 404 Not Found: Signup request not found, or does not belong to this organization.
  • 409 Conflict: Signup request is not in pending_approval state.

POST /api/human/orgs/{org_id}/signup-requests/{request_id}/reject

Reject a pending agent signup request. Any member of the organization can reject.

Auth

  • Session cookie or Authorization: Bearer <sealed-session>

Path Parameters

Name Description
org_id Organization ID
request_id The signup_request_id to reject

Response (200 OK) Returns the updated signup request object with status: "rejected".

Error Responses

  • 401 Unauthorized: Missing or invalid session.
  • 403 Forbidden: Caller is not a member of the organization.
  • 404 Not Found: Signup request not found, or does not belong to this organization.
  • 409 Conflict: Signup request is not in pending_approval state.

POST /api/human/agent_signup

Human-initiated agent signup. The human must be a member of the specified organization. Returns a challenge with a session token prefixed with human-.

Auth

  • Session cookie or Authorization: Bearer <sealed-session>

Request Body

{
  "org_id": "org-550e8400-e29b-41d4-a716-446655440000"
}
Field Required Description
org_id Yes Organization ID — must be an org the authenticated human belongs to

Response (200 OK)

{
  "session_token": "human-aBcDeFgHiJkLmNoP",
  "challenge": "What is the capital of France?"
}

Error Responses

  • 401 Unauthorized: Missing or invalid session.
  • 403 Forbidden: Human is not a member of the specified organization.
  • 422 Unprocessable Entity: Invalid request body.

Notes

  • The returned session_token starts with human- to distinguish it from agentic signups.
  • Complete agent creation using the same POST /api/agentic/signup-commit endpoint.