Site People

Site People routes manage the people attached to a site for a virtual access integration: principals that hold an org role like virtual_access:integration:{id}:*. All three operations require X-Org and api_key (X-API-Key); path id is the integration ULID (see Integrations and Organization context & pagination).

OpenAPI groups these under /integrations/{id}/people (and .../{user_id} for removal). AddSitePersonPayload requires user_id and role strings — paste the role your deployment expects (often scoped to that integration); see schemas in the API reference.

Operations vs wire routes

Concern	HTTP	operationId	Notes
List users	GET .../people	list_people	Path id = integration.200 body is an array per bundle (no named response schema in the public YAML).
Add user	POST .../people	add_person	AddSitePersonPayload. 201 created.
Remove user	DELETE .../people/{user_id}	delete_person	204 empty body on success.

SDK coverage

Capability	Python	Rust (openapp_sdk)	Go	TypeScript (AsyncClient)
List	client.site_people.list(id) → list[dict]	Thin site_people().list omits X-Org — use transport() + RequestSpec (see examples) when the gateway requires the header	DirectoryListingMembersAPI.ListPeople + .XOrg(...)	Not on façade yet
Add	site_people.add(id, user_id=…, role=…)	Same: prefer transport() + RequestSpec below for strict header parity	AddPerson + payload + .XOrg(...)	Not on façade yet
Remove	site_people.remove(id, user_id)	Same	DeletePerson + .XOrg(...)	Not on façade yet

The Go generator returns raw *http.Response for these operations (no typed decode in the client) — decode JSON yourself from Body on success.

Typical errors

401 / 403 for auth and org policy; 404 when the integration (or user, for delete) is missing; 400 for invalid payloads. Error bodies where returned follow ApiErrorResponse — see Errors & retries.

Examples

Constants below stand in for real ULIDs from your org.

Python

rows = await client.site_people.list(integration_id)

OpenAPI requires X-Org on list_people. If your bridge does not inject it from the default org, use interceptors or mirror the transport + RequestSpec pattern from the Rust tab with your HTTP client.

Go

X-Org is mandatory on the request builder.

import (
    "context"
    "encoding/json"
    "io"
)

resp, err := client.DirectoryListingMembersAPI.ListPeople(context.Background(), integrationId).
    XOrg(orgId).
    Execute()
if err != nil {
    return err
}
defer resp.Body.Close()

b, err := io.ReadAll(resp.Body)
if err != nil {
    return err
}
var rows []map[string]any
if err := json.Unmarshal(b, &rows); err != nil {
    return err
}
_ = rows

Rust

X-Org is required on the wire. The high-level site_people() helpers do not attach it — use transport() (same idea as Org context & pagination):

use openapp_sdk::{Client, transport::RequestSpec};
use reqwest::Method;

let client = Client::builder()
    .api_key("https://openapp.house_openapp_YOUR_SECRET")
    .build()?;

let org_id = "01HORG00000000000000000000".to_string();
let path = format!("/integrations/{integration_id}/people");
let rows: Vec<serde_json::Value> = client
    .transport()
    .request_json(RequestSpec {
        method: Method::GET,
        path: &path,
        extra_headers: &[("X-Org", org_id)],
        ..Default::default()
    })
    .await?;

TypeScript

const rows = await fetch(
  `https://openapp.house/api/v1/integrations/${integrationId}/people`,
  {
    headers: {
      "x-api-key": "https://openapp.house_openapp_YOUR_SECRET",
      "x-org": orgId,
    },
  },
).then(
  (r) =>
    r.json() as Promise<Array<{ user_id: string; role: string }>>,
);

The path id is the integration ULID, not the listing / building. X-Org is required by the wire even though the integration id already implies an org. Replace with AsyncClient.listPeople once the Node façade exposes it.

Add and remove a site person

Python

created = await client.site_people.add(
    integration_id,
    user_id=user_ulid,
    role=role_string,
)
await client.site_people.remove(integration_id, user_ulid)

Same X-Org requirement as for GET — ensure the wire request carries the header for POST / DELETE.

Go

import (
    "context"

    openapiclient "github.com/tomers/openapp-sdk/go"
)

payload := *openapiclient.NewAddSitePersonPayload(roleString, userUlid)
resp, err := client.DirectoryListingMembersAPI.AddPerson(context.Background(), integrationId).
    XOrg(orgId).
    AddSitePersonPayload(payload).
    Execute()
if err != nil {
    return err
}
defer resp.Body.Close()

delResp, err := client.DirectoryListingMembersAPI.DeletePerson(
    context.Background(), integrationId, userUlid,
).XOrg(orgId).Execute()
if err != nil {
    return err
}
defer delResp.Body.Close()

Rust

use openapp_sdk::{Client, transport::RequestSpec};
use reqwest::Method;
use serde_json::json;

let client = Client::builder()
    .api_key("https://openapp.house_openapp_YOUR_SECRET")
    .build()?;

let org_id = "01HORG00000000000000000000".to_string();
let add_path = format!("/integrations/{integration_id}/people");
let _created: serde_json::Value = client
    .transport()
    .request_json(RequestSpec {
        method: Method::POST,
        path: &add_path,
        body: Some(&json!({ "user_id": user_ulid, "role": role_string })),
        extra_headers: &[("X-Org", org_id.clone())],
        ..Default::default()
    })
    .await?;

let del_path = format!("/integrations/{integration_id}/people/{user_ulid}");
client
    .transport()
    .request_json::<(), ()>(RequestSpec {
        method: Method::DELETE,
        path: &del_path,
        extra_headers: &[("X-Org", org_id)],
        ..Default::default()
    })
    .await?;

TypeScript

const sitePeopleUrl = `https://openapp.house/api/v1/integrations/${integrationId}/people`;
const headers = {
  "x-api-key": "https://openapp.house_openapp_YOUR_SECRET",
  "content-type": "application/json",
  "x-org": orgId,
};

const created = await fetch(sitePeopleUrl, {
  method: "POST",
  headers,
  body: JSON.stringify({ user_id: userUlid, role: roleString }),
}).then((r) => r.json());

await fetch(`${sitePeopleUrl}/${userUlid}`, {
  method: "DELETE",
  headers: {
    "x-api-key": "https://openapp.house_openapp_YOUR_SECRET",
    "x-org": orgId,
  },
});

Body matches AddSitePersonPayload (user_id + role strings; the role is the integration-scoped grant your deployment expects, often virtual_access:integration:{id}:resident). DELETE returns 204 with no body. Replace each fetch with the Node façade once it exposes site-people methods.