@kody/workos
Manage WorkOS organizations, AuthKit users, SSO, and Directory Sync with dry-run writes.
Files
@kody/workos
Intent
Reusable WorkOS helpers so Kody agents can inspect the caller's
organizations, AuthKit users, SSO connections, Directory Sync directories, and
events — not a shared platform tenant. Auth is a saved environment API key
(sk_test_… or sk_live_…). Reads are free-form. Mutations support
dryRun: true, and live writes also require confirm: true.
This listing is meant to be forked. After you fork, save your own
workosApiKey and call the helpers in your account. No personal organization
ids, user emails, or API keys are hard-coded.
Share this package as https://kody.codes/@kody/workos
(never a /community/{listing_id} URL).
What it does
- List and get organizations; create / update / delete with dry-run guards
- List and get AuthKit users
- List SSO connections, Directory Sync directories, and directory users
- List events by type; generate Admin Portal setup links
- Low-level
requestescape hatch for other WorkOS REST paths
Prerequisites / setup
WorkOS server APIs use an environment API key. There is no built-in Kody OAuth app for WorkOS.
| Secret | Purpose |
|---|---|
workosApiKey | Environment API key (sk_test_… / sk_live_…) |
- Create a key in the WorkOS Dashboard → API keys.
Use a test key (
sk_test_…) until you explicitly need production. - Save it in Kody (do not paste the value in chat):
https://kody.codes/account/secrets/new?name=workosApiKey&description=WorkOS%20API%20key%20(Bearer%20token%20for%20api.workos.com)&allowedHosts=api.workos.com&scope=user
- In the account secrets UI, approve host
api.workos.com. - Smoke-test with
./smoke-test(agents: seeAGENTS.md).
Pass account: "work" to use secret workosApiKey-work, or pass
secretName: "workosApiKey-work". There are no hard-coded account aliases.
A WorkOS Client ID is only needed for AuthKit/SSO login URLs in your app. These
helpers talk to https://api.workos.com with the API key and do not store a
client id.
Hosts
api.workos.com— all REST calls (required)
Mutation safety
Mutating helpers support dryRun: true and refuse live writes unless
confirm: true. Agents: import paths, smoke snippets, and confirm examples live
in AGENTS.md.
Done when
workosApiKeyis saved; hostapi.workos.comand package secret access are approved- Smoke test returns
ok: true(live org sample when the key exists; no user emails) - Destructive helpers refuse unless
confirm: true;dryRun: truenever writes
Branding
community-icon.svg is WorkOS's official color logomark from the public
WorkOS Logos press kit (WorkOS_Logomark_White.svg on brand color #6363F1).
Paths are unmodified except for a square tile so the mark stays legible at 56
pixels.
WorkOS® is a trademark of WorkOS, Inc. This package is not affiliated with or
endorsed by WorkOS.