Organizations (Orgs)

Endpoints under the Orgs tag manage organizations (tenants) the caller can access: list and CRUD, permissions for the current principal, org-scoped user listing, soft delete, and hard purge. Response bodies follow OrganizationResponse and related schemas in the API reference.

Relationship to org context: Choosing X-Org for device and integration routes is separate from these APIs — see Organization context & pagination. Use GET /orgs to discover org ids when the account spans multiple organizations.

Operations vs wire routes

Concern	HTTP	`operationId`	Notes
List	`GET /orgs`	`list_orgs`	Requires `output_options` and `pagination` query objects on the wire (see bundle).
Create	`POST /orgs`	`create_org`	Body `CreateOrganizationRequest` (`name` required; optional `description`, `parent_id`). The server assigns the id; any other field is rejected with 422.
Get	`GET /orgs/{id}`	`get_org`
Update	`PUT /orgs/{id}`	`update_org`	Partial-style body per `UpdateOrganizationRequest`.
Soft delete	`DELETE /orgs/{id}`	`delete_org`
Hard delete	`DELETE /orgs/{id}/purge`	`hard_delete_org`
Caller permissions	`GET /orgs/{id}/permissions`	`get_org_permissions`	Permissions for the current user in that org. Returns an empty list (not an error) when the caller has no standing in the org, including when it does not exist.
Users in org	`GET /orgs/{org_id}/users`	`list_org_users`	Requires `X-Org`, `output_options`, `pagination`; optional `recursive` query.

SDK coverage

Capability	Python	Rust (`openapp_sdk`)	Go	TypeScript (`AsyncClient`)
List	`client.orgs.list(...)` — forwards `output_options` / pagination fields via the bridge	`client.orgs().list()` — bare `GET /orgs` without required query objects; use `transport()` + `RequestSpec` for OpenAPI parity	`OrgsAPI.ListOrgs` with full query builders	`listOrgs` — bare `GET /orgs`
Create	`client.orgs.create(name=..., **extra)`	`client.orgs().create(&json!)`	`OrgsAPI.CreateOrg`	`createOrg(name)` — sends `{ name }` only
Get / update / delete / purge	`get`, `update`, `delete`, `purge`	`get`, `update`, `delete`, `purge`	Generated `OrgsAPI`	`getOrg` only — no update/delete helpers on façade
Permissions	`permissions(org_id)`	`permissions(id)`	`GetOrgPermissions`	Not on façade — use core `transport` or another SDK
List org users	`users(org_id, ...)`	`users(org_id)` — bare path; wire may require headers/queries	`ListOrgUsers`	Not on façade

Python additionally exposes upload_image / upload_image_from_url for POST /orgs/{id}/image (multipart) where your deployment exposes that route; see Python — Resources.

Typical errors

401 / 403 when the key cannot access the org.404 for unknown org ids.400 on create/update validation. Hard delete may fail when the server rejects purge preconditions. Shapes follow ApiErrorResponse — see Errors & retries.

Examples

List organizations

client.orgs.list maps kwargs to the list_orgs query parameters (include_deleted, limit, cursor, …) expected by your deployment.

page = await client.orgs.list(limit=50)

ListOrgs requires OutputOptions and Pagination.

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

resp, httpResp, err := client.OrgsAPI.ListOrgs(ctx).
    OutputOptions(*openapiclient.NewMultiResourceOutputOptionsQuery()).
    Pagination(openapiclient.PaginationQuery{
        Limit:  openapiclient.PtrInt32(50),
        Offset: openapiclient.PtrInt32(0),
    }).
    Execute()
if err != nil {
    return err
}
defer httpResp.Body.Close()

Thin client.orgs().list() omits required OpenAPI query bundles; use Transport with a RequestSpec when you need list_orgs parity (same idea as Organization context & pagination).

use openapp_sdk::Client;

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

let orgs = client.orgs().list().await?;

import { AsyncClient } from "@tomers/openapp-sdk";

const client = new AsyncClient("https://openapp.house_openapp_YOUR_SECRET");
const raw = await client.listOrgs();

The façade does not yet mirror output_options / pagination on GET /orgs — prefer Python or Go when you need full wire parity.

Create an organization

org = await client.orgs.create(name="Field Office", parent_id="01HPARENT000000000000000000")

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

name := *openapiclient.NewLocalizedString(map[string]string{"en": "Field Office"})
body := openapiclient.NewCreateOrganizationRequest(name)
body.SetParentId("01HPARENT000000000000000000")

resp, httpResp, err := client.OrgsAPI.CreateOrg(ctx).CreateOrganizationRequest(*body).Execute()
if err != nil {
    return err
}
defer httpResp.Body.Close()

use openapp_sdk::Client;
use serde_json::json;

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

let org = client
    .orgs()
    .create(&json!({
        "name": { "en": "Field Office" },
        "parent_id": "01HPARENT000000000000000000"
    }))
    .await?;

import { AsyncClient } from "@tomers/openapp-sdk";

const client = new AsyncClient("https://openapp.house_openapp_YOUR_SECRET");
const raw = await client.createOrg("Field Office");

Use Python, Rust, or Go when you need description, parent_id, or other CreateOrganizationRequest fields beyond name.

Get / update / delete / purge (`/orgs/{id}`)

update_org accepts an UpdateOrganizationRequest (optional name as LocalizedString, description, parent_id). delete_org is reversible at the data layer; hard_delete_org removes the row irrecoverably.

org = await client.orgs.get(org_id)
updated = await client.orgs.update(org_id, name={"value": {"en": "Field Office (renamed)"}})
await client.orgs.delete(org_id)
await client.orgs.purge(org_id)

import (
    "context"

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

org, httpResp, err := client.OrgsAPI.GetOrg(context.Background(), orgID).Execute()
if err != nil {
    return err
}
defer httpResp.Body.Close()
_ = org

upd := openapiclient.NewUpdateOrganizationRequest()
upd.SetName(*openapiclient.NewLocalizedString(map[string]string{"en": "Field Office (renamed)"}))
updated, httpResp2, err := client.OrgsAPI.UpdateOrg(context.Background(), orgID).
    UpdateOrganizationRequest(*upd).
    Execute()
if err != nil {
    return err
}
defer httpResp2.Body.Close()
_ = updated

_, httpResp3, err := client.OrgsAPI.DeleteOrg(context.Background(), orgID).Execute()
if err != nil {
    return err
}
defer httpResp3.Body.Close()

_, httpResp4, err := client.OrgsAPI.HardDeleteOrg(context.Background(), orgID).Execute()
if err != nil {
    return err
}
defer httpResp4.Body.Close()

use openapp_sdk::Client;
use serde_json::json;

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

let org = client.orgs().get(org_id).await?;
let updated = client
    .orgs()
    .update(
        org_id,
        &json!({ "name": { "value": { "en": "Field Office (renamed)" } } }),
    )
    .await?;
client.orgs().delete(org_id).await?;
client.orgs().purge(org_id).await?;

import { AsyncClient } from "@tomers/openapp-sdk";

const client = new AsyncClient(
  "https://openapp.house_openapp_YOUR_SECRET",
);

const org = await client.getOrg(orgId);

const updated = await fetch(`https://openapp.house/api/v1/orgs/${orgId}`, {
  method: "PUT",
  headers: {
    "x-api-key": "https://openapp.house_openapp_YOUR_SECRET",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    name: { value: { en: "Field Office (renamed)" } },
  }),
}).then((r) => r.json());

await fetch(`https://openapp.house/api/v1/orgs/${orgId}`, {
  method: "DELETE",
  headers: { "x-api-key": "https://openapp.house_openapp_YOUR_SECRET" },
});
await fetch(`https://openapp.house/api/v1/orgs/${orgId}/purge`, {
  method: "DELETE",
  headers: { "x-api-key": "https://openapp.house_openapp_YOUR_SECRET" },
});

The Node façade ships getOrg but not the mutation helpers — pair it with raw fetch for PUT|DELETE /orgs/{id} and DELETE /orgs/{id}/purge. UpdateOrganizationRequest wraps name in LocalizedString ({ value: { en: "…" } }); soft delete is reversible until /purge runs. Replace each fetch with AsyncClient lifecycle helpers once the Node façade exposes them.

Caller permissions and org members

get_org_permissions returns the permissions held by the calling principal in that org (use it to drive UI gating). list_org_users enumerates members and accepts an optional recursive flag to include descendant orgs; the route requires X-Org plus output_options + pagination on the wire.

perms = await client.orgs.permissions(org_id)
members = await client.orgs.users(org_id, limit=50)

For recursive parity with list_org_users, send the request via AsyncClient._request with the explicit query key.

perms, httpResp, err := client.OrgsAPI.GetOrgPermissions(ctx, orgID).Execute()
if err != nil {
    return err
}
defer httpResp.Body.Close()
_ = perms

members, httpResp2, err := client.OrgsAPI.ListOrgUsers(ctx, orgID).
    XOrg(orgID).
    OutputOptions(*openapiclient.NewMultiResourceOutputOptionsQuery()).
    Pagination(openapiclient.PaginationQuery{
        Limit:  openapiclient.PtrInt32(50),
        Offset: openapiclient.PtrInt32(0),
    }).
    Recursive(true).
    Execute()
if err != nil {
    return err
}
defer httpResp2.Body.Close()
_ = members

use openapp_sdk::Client;

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

let perms = client.orgs().permissions(org_id).await?;
let members = client.orgs().users(org_id).await?;

users() issues a bare GET /orgs/{id}/users; build a RequestSpec on client.transport() when you need X-Org, output_options, pagination, or recursive=true.

const perms = await fetch(
  `https://openapp.house/api/v1/orgs/${orgId}/permissions`,
  { headers: { "x-api-key": "https://openapp.house_openapp_YOUR_SECRET" } },
).then((r) => r.json() as Promise<{ permissions: string[] }>);

const usersUrl = new URL(`https://openapp.house/api/v1/orgs/${orgId}/users`);
usersUrl.searchParams.set("limit", "50");
usersUrl.searchParams.set("offset", "0");
usersUrl.searchParams.set("include_deleted", "false");
usersUrl.searchParams.set("recursive", "true");

const members = await fetch(usersUrl, {
  headers: {
    "x-api-key": "https://openapp.house_openapp_YOUR_SECRET",
    "x-org": orgId,
  },
}).then((r) => r.json() as Promise<{ items: Array<{ id: string }> }>);

/permissions returns the calling principal’s permissions in that org (use it to gate UI). /users requires X-Org plus the flat output_options / pagination keys; pass recursive=true to include descendant orgs. Replace each fetch with AsyncClient helpers once the Node façade exposes them.