Organization context & pagination

Most API keys are created under a single organization in the dashboard; authorization and roles are evaluated in that org’s context. Some accounts participate in multiple organizations. Wire-level list endpoints then combine organization selection (X-Org and related query fields) with pagination query parameters described in the canonical OpenAPI bundle.

This page ties those concepts to each SDK. For installation and credentials, start with Authentication.

Organization context

Concept	Details
Key issuance	Keys are minted while an organization is selected in the dashboard; role checks apply in that org. See API keys.
Multi-org users	Call GET /orgs (list orgs your principal can access) and choose a target org id before hitting org-scoped routes.
X-Org header	Many operations are documented as “for the organization context (X-Org)”. Pass the organization id (ULID string) when connecting the client — every SDK attaches it automatically. For multi-org scripts, use the scoped-client helpers below. OpenAPI lists which operations require it — see the API reference.
orgId query	Some list surfaces accept an orgId filter in addition to X-Org. Prefer matching the same org id in both when your generator or SDK exposes both.

SDK helpers

Set a default org at connect time, or clone a scoped client for a different org:

Python

from openapp_sdk import Client

# Default org for every request
client = Client.connect(api_key="...", org_id="01HORG00000000000000000000")

# Multi-org: scoped clone
other = client.with_org("01HORG00000000000000000001")

Rust

use openapp_sdk::Client;

let client = Client::builder()
    .api_key("https://api.openapp.house/api/v1_openapp_YOUR_SECRET")
    .org("01HORG00000000000000000000")
    .build()?;

let other = client.with_org("01HORG00000000000000000001");

TypeScript

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

const client = new AsyncClient("https://api.openapp.house/api/v1_openapp_YOUR_SECRET", {
  org: "01HORG00000000000000000000",
});

const other = client.withOrg("01HORG00000000000000000001");

Go

The generated client exposes .XOrg(id) on each operation (per-call builder). For a single org, pass the same id on every call:

client.IntegrationsAPI.CreateIntegrationAccessInvite(ctx, integrationID).
    XOrg("01HORG00000000000000000000").
    CreateAccessInviteRequest(*req).
    Execute()

Errors: Missing or invalid org context typically surfaces as 403 Forbidden or 404 depending on the route and server rules, in addition to the usual 401 when the key is invalid.

Pagination on list endpoints

The public API describes list operations with:

• output_options — MultiResourceOutputOptionsQuery in the OpenAPI bundle (include_deleted, include_metadata, only_deleted — all required on the wire in the published schema).
• pagination — PaginationQuery: limit (page size, server-enforced max typically 200) and offset (items to skip).

Response shape for paginated JSON bodies is typically PaginatedResponse: items (array) and total (count). Some SDK-level wrappers may expose cursor-style helpers on top of the same routes; where that applies, see Python — Resources for iteration patterns.

When in doubt, use the interactive API reference for the exact parameters and schemas of the operation you are calling.

Examples

List devices in an organization

Python

devices.list accepts optional org_id, limit, and cursor kwargs. Set org context at connect time so X-Org is sent automatically:

client = Client.connect(api_key="...", org_id="01HORG00000000000000000000")
rows = await client.devices.list(limit=50)

For large org listings and other resources, combine limit with the pagination fields returned by the API (for example a next_cursor when the service emits one — see Resources).

Go

The generated client requires X-Org, OutputOptions, and Pagination for ListDevices.

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

resp, httpResp, err := client.DevicesAPI.ListDevices(ctx).
    XOrg("01HORG00000000000000000000").
    OutputOptions(*openapiclient.NewMultiResourceOutputOptionsQuery(false, false, false)).
    Pagination(openapiclient.PaginationQuery{Limit: openapiclient.PtrInt32(50), Offset: openapiclient.PtrInt32(0)}).
    Execute()
if err != nil {
    return err
}
defer httpResp.Body.Close()
// resp is []openapiclient.DeviceResponse

Rust

Set org context on the builder — high-level sub-clients then send X-Org on every request:

use openapp_sdk::Client;

let client = Client::builder()
    .api_key("https://api.openapp.house/api/v1_openapp_YOUR_SECRET")
    .org("01HORG00000000000000000000")
    .build()?;

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

Extend list calls with output_options and pagination query encoding when your deployment requires them.

TypeScript

Pass org when constructing AsyncClient:

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

const client = new AsyncClient("https://api.openapp.house/api/v1_openapp_YOUR_SECRET", {
  org: "01HORG00000000000000000000",
});
const devices = await client.devices.list();

List organizations (discovery)

Python

page = await client.orgs.list(limit=50)
for org in page.get("items", []):
    print(org.get("id"), org.get("name"))

Go

ListOrgs requires OutputOptions and Pagination:

import (
    "context"

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

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

Rust

use openapp_sdk::Client;

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

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

If you need full pagination parity with OpenAPI, issue a transport-level GET /orgs with explicit output_options / pagination query serialization.

TypeScript

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

const client = new AsyncClient("https://api.openapp.house/api/v1_openapp_YOUR_SECRET");
const orgs = await client.listOrgs();

The returned value is parsed JSON from GET /orgs; narrow the type in your application as needed.

Related

• Authentication — constructing clients and bearer tokens.
• Python — Resources — sub-clients, payload conventions, and pagination snippets.
• API reference — authoritative parameters per operation.