FruxonDocs
Agent NetworkParticipants

Approves an access request and materializes the proposed addition to the participant graph.

Body's `mode` picks the commit shape: <list type="bullet"><item><b>createNew</b> — create a new Person participant from the observed sender, with one channel `{integrationConfigId, address}` from the request, and bind it to the request's agent.</item><item><b>addToExisting</b> — append the channel to an operator-chosen existing participant (`participantId` required) and ensure the binding to the request's agent.</item><item><b>bindOnly</b> — write just the agent binding; the channel already exists on the matched participant.</item></list> Returns 400 if the request is not in Pending, or if the requested mode is missing the field it requires (e.g. `bindOnly` on a request without a matched participant). Requires Editor role on the request's agent — enforced inside the service since the route doesn't carry the agent id.

POST
/v1/tenants/{tenant}/participantAccessRequests/{participantAccessRequest}:approve

Authorization

Bearer
AuthorizationBearer <token>

JWT Authorization header using the Bearer scheme. Enter 'Bearer' [space] and then your token.

In: header

Path Parameters

participantAccessRequest*string

The participant access request ID.

Formatuuid
tenant*string

The tenant identifier

Request Body

Approve payload — mode + mode-conditional fields.

mode?string

How an access request commits on approve. See §11 of agent-network.md.

Value in"UNSPECIFIED" | "CREATE_NEW" | "ADD_TO_EXISTING" | "BIND_ONLY"
displayName?string|null

Operator-supplied name for the new participant. Optional in createNew mode — falls back to the request's DisplayName, then to the address. Ignored in the other modes.

Lengthlength <= 150
participantId?string|null

Existing participant to extend / bind. Required in addToExisting mode; ignored otherwise (in bindOnly the matched participant is read off the request row itself).

Formatuuid
note?string|null

Optional audit note recorded on the request row.

Lengthlength <= 4000
area?string|null

Optional onboarding enrichment for createNew mode — the operator captures who this person is at the moment they admit them, so the agent's get_user_info can tailor replies immediately. Mirror the Fruxon.Model.Participants.CreateParticipantRequest profile fields; ignored in the other modes (the participant already exists).

Lengthlength <= 150
bio?string|null
Lengthlength <= 4000
description?string|null
Lengthlength <= 4000
environmentId?string|null

Environment (served end-customer / account) to file the new contact under, in createNew mode. Authoritative only when Fruxon.Model.Participants.AccessRequests.ApproveAccessRequestRequest.EnvironmentSpecified is true (an env-aware UI accepted / changed / cleared the suggestion — a null then means "no environment"). When false, the approve path applies the per-provider resolver's suggestion derived from the captured provider facts. Ignored in the other modes (the participant already exists). Supersedes the retired OrganizationId (docs/design/environments-directory-unification.md).

Formatuuid
environmentSpecified?boolean

True when the client set Fruxon.Model.Participants.AccessRequests.ApproveAccessRequestRequest.EnvironmentId deliberately (env-aware UI). False — the default, and what a legacy client sends — lets the approve path fall back to the provider resolver's suggestion. Distinguishes "explicitly none" from "field omitted".

[key: string]?never

Response Body

curl -X POST "https://api.fruxon.com/v1/tenants/string/participantAccessRequests/497f6eca-6276-4993-bfeb-53cbbbba6f08:approve" \  -H "Content-Type: application/json" \  -d '{}'
{
  "id": "00000000-0000-0000-0000-000000000000",
  "integrationConfigId": "00000000-0000-0000-0000-000000000000",
  "provider": "string",
  "address": "string",
  "agentId": "string",
  "matchedParticipantId": "00000000-0000-0000-0000-000000000000",
  "networkId": "00000000-0000-0000-0000-000000000000",
  "displayName": "string",
  "conversationName": "string",
  "status": "PENDING",
  "processedBy": "string",
  "processedAt": 0,
  "processingNote": "string",
  "approvedParticipantId": "00000000-0000-0000-0000-000000000000",
  "capturedAttributes": {},
  "suggestedEnvironment": {
    "environmentId": "00000000-0000-0000-0000-000000000000",
    "displayName": "string",
    "isNew": false
  },
  "createdAt": 0,
  "modifiedAt": 0
}
{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}
Empty
{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}
{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Lists access requests in the tenant, filterable by agent / status / matched-or-approved participant.

The Agent Network overview tab calls this with `agentId` set to the current agent and `status=pending` to render the pending queue. The tenant-level triage page calls it without filters. Returns every match — paging is intentionally not modelled in v1 because the pending queue is bounded by operator throughput, not message volume.

Retrieves a specific access request by ID.

Loads the full access request row for operator review, including the proposed sender channel, matched participant (when one was found), and processing metadata. Use this before approving or rejecting when the list view does not include enough context for the decision.