@opensteward/sdk — getting started
Official TypeScript SDK for OpenSteward. Two clients in one package:
- Public client — for tenant developers consuming the unified
/v1/*integration API. Auth: tenant Bearer API key (osk_…), or an OIDC bearer token from the operator’s identity provider. - Operator client — for operators and CI scripts driving the
admin-api (
/api/*). Auth: JWT issued byPOST /api/auth/login, with built-in helpers to manage it.
Both clients are generated from the committed OpenAPI specs
(docs/openapi/openapi.json and docs/openapi/admin-api.openapi.json),
so every route in either spec is type-checked at compile time. Adding
or renaming a route in the source spec → rerun pnpm sdk:generate →
the new path appears in the SDK with no manual editing.
Install
Section titled “Install”pnpm add @opensteward/sdk# or: npm i @opensteward/sdk# or: yarn add @opensteward/sdkNeeds a runtime with global fetch; the package declares no engines
floor of its own, and the monorepo builds on Node 24+. No browser-only
dependencies — the public client runs in browsers and on Node; the
operator client’s fromCredentialsFile() helper is Node-only because it
reads disk.
Public client (tenant developer)
Section titled “Public client (tenant developer)”import { createPublicClient } from '@opensteward/sdk'
const client = createPublicClient({ baseUrl: 'http://localhost:3010', apiKey: process.env.OPENSTEWARD_API_KEY!,})
// Typed end-to-end: path, query params, response shape.const { data, error } = await client.GET('/customers', { params: { query: { limit: 10 } },})
if (error) { console.error('list failed', error) process.exit(1)}
for (const c of data!.data) { console.log(c.id, c.displayName)}baseUrl is the bare host — no /v1. The client appends the version
segment itself, per path (details below). A baseUrl ending in /v1
double-prefixes to /v1/v1/… and 404s on every call.
Test mode (sandbox)
Section titled “Test mode (sandbox)”Pass mode: 'test' and every versioned call routes to the deployment’s
/test/v1/* sandbox — synthetic data seeded from the documented schema
examples, no upstream calls, and writes that persist until
DELETE /test/v1/reset:
const sandbox = createPublicClient({ baseUrl: 'http://localhost:3010', mode: 'test', // default: 'live' apiKey: process.env.OPENSTEWARD_TEST_API_KEY!, // a key minted with --test})
// Discover the sandbox's synthetic connection ids — no setup step needed.const { data } = await sandbox.GET('/test/v1/connections')The two modes never share a credential: a live key on /test/v1/* answers
403 KEY_MODE_MISMATCH, and so does the reverse. Going to production is
therefore exactly two edits: drop mode: 'test' and swap in the live key.
The sandbox accepts osk_test_ keys only — OIDC bearer tokens are refused
there by design (the verifier would need egress the sandbox promises not
to have).
Authenticating with an OIDC token instead
Section titled “Authenticating with an OIDC token instead”Where the deployment’s operator has registered an identity provider, the
same routes accept a short-lived token from it. Pass getAccessToken
instead of apiKey — a function rather than a string, because tokens
expire and the client has to be able to ask again:
import { createPublicClient, clientCredentialsTokenSource } from '@opensteward/sdk'
const client = createPublicClient({ baseUrl: 'http://localhost:3010', getAccessToken: clientCredentialsTokenSource({ tokenUrl: 'https://idp.example.com/oauth/token', clientId: process.env.IDP_CLIENT_ID!, clientSecret: process.env.IDP_CLIENT_SECRET!, // The API identifier the operator registered as the issuer's audience. audience: 'https://opensteward.internal', }),})clientCredentialsTokenSource caches the token until a minute before it
expires and collapses concurrent callers into one request, so a busy
client does not hammer the token endpoint. It is deliberately small —
if you already have an OAuth library, hand getAccessToken whatever it
gives you:
const client = createPublicClient({ baseUrl: 'http://localhost:3010', getAccessToken: () => myOAuthLibrary.getValidAccessToken(),})Nothing else changes. The token resolves to the same scopes an API key
does, so every route, error and scope rule below applies identically.
Two responses are specific to this pairing: 403 OAUTH_DISABLED means
the deployment does not accept OIDC tokens, and 403 API_KEYS_DISABLED
means it no longer accepts osk_ keys — ask the operator which they
have enabled. Verification failures all answer the same
401 UNAUTHENTICATED, deliberately, so the response cannot be used to
enumerate the operator’s service accounts.
Every operation in docs/openapi/openapi.json is callable. Use
client.GET, client.POST, client.PUT, client.PATCH, client.DELETE
with a path that exists in the spec — your IDE autocompletes both the
path and the request shape. Successful list responses are enveloped:
{ data: [...] }, usually with a meta alongside it.
baseUrl and the version prefix
Section titled “baseUrl and the version prefix”The spec keeps two namespaces (see
dev-api.md §11), and
the client reconciles them so one instance serves both:
- Versioned —
/customers,/accounting/invoices,/{vertical}/syncand friends are written without a version prefix in the spec. The client prepends/v1(or/test/v1in test mode) to these on the wire. - Unversioned —
/health,/auth/*,/admin/*,/webhooks/*and the sandbox control routes spell their real path in full and are sent as-is; a generated set (public-unversioned.ts) says which, so it cannot drift from the spec.
So: always pass the bare host. There is no need for a second client
instance, and a baseUrl that already carries /v1 is the one
configuration that breaks.
Operator client (CLI / CI scripts)
Section titled “Operator client (CLI / CI scripts)”import { createOperatorClient } from '@opensteward/sdk'
const op = createOperatorClient({ baseUrl: 'http://localhost:3001' })
// 1. Login — stores the JWT inside the client instance.await op.login('admin', process.env.OS_PASSWORD!)
// 2. Make typed calls. Authorization header is added automatically.const { data } = await op.GET('/api/users', {})console.table(data?.data)
// 3. Done.await op.logout()Reusing a token
Section titled “Reusing a token”.login() is one of three ways to put a token on the client:
// (a) From an existing JWT (env var, another script, etc.)op.setToken(process.env.OS_TOKEN!)
// (b) From a credentials file on disk (the path the `os` CLI writes:// ~/.config/opensteward/credentials.json).op.fromCredentialsFile('/Users/me/.config/opensteward/credentials.json')
// (c) `await op.login(user, pw)` — covered above.@opensteward/cli writes that file from os setup, whose first step signs
in and persists the JWT to ~/.config/opensteward/credentials.json (file
mode 0600, directory 0700). os auth login mints a JWT too, but — like
every mechanically generated command — it prints the response rather than
saving it. fromCredentialsFile() is the supported way to pick the stored
token up in scripts without re-prompting for credentials. Full command
reference: operations/cli.md.
Inspecting / clearing the token
Section titled “Inspecting / clearing the token”op.getToken() // returns the stored JWT, or `null`op.setToken(null) // clear without calling the APIawait op.logout() // POSTs /api/auth/logout, then clearsType-level access to operations
Section titled “Type-level access to operations”The package re-exports the underlying paths types so you can derive
your own helper types per operation:
import type { PublicPaths, OperatorPaths } from '@opensteward/sdk'
type ListCustomersResponse = PublicPaths['/customers']['get']['responses']['200']['content']['application/json']
type CreateUserBody = OperatorPaths['/api/users']['post']['requestBody']['content']['application/json']Error shape
Section titled “Error shape”openapi-fetch returns { data, error, response } — a tagged union
where success has data set and failure has error. The HTTP
Response is always available for callers that need raw access
(headers, status, body stream).
const { data, error, response } = await client.GET('/customers', {})if (error) { console.error(`HTTP ${response.status}`, error)}Versioning
Section titled “Versioning”The SDK ships in lock-step with the OpenSteward release that produced
its specs. A spec change → pnpm sdk:generate runs as part of
pnpm docs:all. CI fails (pnpm check:docs) if the committed
generated files drift from the live specs, so the published SDK surface
always matches the specs.
opensteward.dev ·Plans and free license ·Terms ·Privacy ·support@opensteward.dev
© 2026 Falco Consulting AB. Built from open-steward/opensteward@a3961d8. This site sets no cookies, runs no analytics and loads nothing from other sites, except platform logos from Brandfetch on the Platforms page.