# @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 `request` escape 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_…`) | 1. Create a key in the [WorkOS Dashboard → API keys](https://dashboard.workos.com/api-keys). Use a test key (`sk_test_…`) until you explicitly need production. 2. 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 3. In the account secrets UI, approve host `api.workos.com`. 4. Smoke-test with `./smoke-test` (agents: see [`AGENTS.md`](./AGENTS.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`](./AGENTS.md). ## Done when - `workosApiKey` is saved; host `api.workos.com` and 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: true` never 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. ## Docs - [WorkOS documentation](https://workos.com/docs) - [API reference](https://workos.com/docs/reference) - [Organizations](https://workos.com/docs/reference/organization) - [Users](https://workos.com/docs/reference/user-management/user) - [SSO connections](https://workos.com/docs/reference/sso/connection) - [Directory Sync](https://workos.com/docs/reference/directory-sync) - [Events](https://workos.com/docs/reference/events) - [Admin Portal](https://workos.com/docs/reference/admin-portal)