@kody/workos
Manage WorkOS organizations, AuthKit users, SSO, and Directory Sync with dry-run writes.
Files
@kody/workos — agent notes
Human setup and intent live in README.md. This file is for
agents: imports, smoke/dryRun execute snippets, and edge cases. Secrets by
name only — never paste key values. Do not disable live webhooks or jobs.
Secrets
| Name | Purpose |
|---|---|
workosApiKey | Default environment API key (sk_test_… / sk_live_…); host api.workos.com |
workosApiKey-<label> | Extra account via account: "<label>" or secretName |
Placeholder shape: {{secret:workosApiKey|scope=user}}. There is no built-in
WorkOS OAuth app.
Import paths
| Export | Import |
|---|---|
root dispatcher (default smoke-test) | kody:@kody/workos |
| accounts | kody:@kody/workos/accounts |
| smoke-test | kody:@kody/workos/smoke-test |
| list-organizations | kody:@kody/workos/list-organizations |
| get-organization | kody:@kody/workos/get-organization |
| create-organization | kody:@kody/workos/create-organization |
| update-organization | kody:@kody/workos/update-organization |
| delete-organization | kody:@kody/workos/delete-organization |
| list-users | kody:@kody/workos/list-users |
| get-user | kody:@kody/workos/get-user |
| list-connections | kody:@kody/workos/list-connections |
| list-directories | kody:@kody/workos/list-directories |
| list-directory-users | kody:@kody/workos/list-directory-users |
| list-events | kody:@kody/workos/list-events |
| create-portal-link | kody:@kody/workos/create-portal-link |
| request | kody:@kody/workos/request |
| types | kody:@kody/workos/types |
Prefer static kody:@kody/workos/... imports from execute. Do not lead with
packages.invoke.
Smoke test (read-only)
import smokeTest from 'kody:@kody/workos/smoke-test'
export default async function main() {
return await smokeTest()
// Without workosApiKey: { ok: true, live: false, setup: { setupUrl, ... } }
// With key: lists one org; does not return user emails
}Dry-run via root dispatcher (no network):
import workos from 'kody:@kody/workos'
export default async function main() {
return await workos({ dryRun: true })
}dryRun / confirm
Pass dryRun: true on create-organization, update-organization,
delete-organization, create-portal-link, and mutating request calls to
return { dryRun: true, wouldCall } without contacting WorkOS. Those same
writes also throw unless confirm: true.
import createOrganization from 'kody:@kody/workos/create-organization'
export default async function main() {
return await createOrganization({
name: 'Acme',
dryRun: true,
})
}Edge cases / fork notes
- REST base:
https://api.workos.com. List helpers return{ items, pageInfo }. list-eventsrequiresevents(WorkOS rejects an unfiltered stream).- Admin Portal intents:
sso,dsync,audit_logs,log_streams,domain_verification,certificate_renewal. account: "work"→ secretworkosApiKey-work; or passsecretName.- Get helpers accept id, or
externalIdwithlookup: "external". - After fork, save the caller's
workosApiKey— do not treat live@kody/workosas a shared tenant. KeepdryRun/confirmguards.