Skip to content
← Public packages

@kody/workos

Manage WorkOS organizations, AuthKit users, SSO, and Directory Sync with dry-run writes.

FollowFork

IntegrationsTopics: workos, authkit, sso, directory-sync, scim, organizations, users, admin-portal, api-key, dry-run

Version
1.0.0
License
MIT
Published
September 10, 2026
Pinned commit
a965573
Rating
No ratings yet
Forks
0
Adaptation effort
—

README

Agent docs

@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.

SecretPurpose
workosApiKeyEnvironment API key (sk_test_… / sk_live_…)
  1. Create a key in the WorkOS Dashboard → 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

  1. In the account secrets UI, approve host api.workos.com.
  2. Smoke-test with ./smoke-test (agents: see 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.

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

Report this listing

Log in to report this listing.