@kody/workos

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

Auth

WorkOS server APIs use an environment API key. There is no built-in Kody OAuth app for WorkOS.

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

3. In the account secrets UI, approve host api.workos.com.
4. Smoke-test with ./smoke-test (see Smoke test).

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

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'

const preview = await createOrganization({
	name: 'Acme',
	dryRun: true,
})

const created = await createOrganization({
	name: 'Acme',
	confirm: true,
})

Smoke test

Run this from execute after the API key is saved. Prefer packages.invoke so secret mounts run in package runtime.

import { packages } from 'kody:runtime'

export default async function main() {
	return await packages.invoke({
		kodyId: 'workos',
		exportName: './smoke-test',
	})
}

Pass the bare kody id workos, not @kody/workos. From an ad hoc execute module you can also import smokeTest from 'kody:@kody/workos/smoke-test'.

Without workosApiKey this still returns { ok: true, live: false } plus the setup URL. With credentials it lists one organization and does not return user emails.

Dry-run preview (no network):

import workos from 'kody:@kody/workos'

export default async function main() {
	return await workos({ dryRun: true })
}

Exports

• kody:@kody/workos — action dispatcher (defaults to smoke-test)
• kody:@kody/workos/accounts — resolve secret name and setup URL
• kody:@kody/workos/smoke-test — credential smoke test (read-only)
• kody:@kody/workos/list-organizations — list organizations (read-only)
• kody:@kody/workos/get-organization — organization detail (read-only)
• kody:@kody/workos/create-organization — create an organization (dryRun / confirm)
• kody:@kody/workos/update-organization — update an organization (dryRun / confirm)
• kody:@kody/workos/delete-organization — delete an organization (dryRun / confirm)
• kody:@kody/workos/list-users — list AuthKit users (read-only)
• kody:@kody/workos/get-user — AuthKit user detail (read-only)
• kody:@kody/workos/list-connections — list SSO connections (read-only)
• kody:@kody/workos/list-directories — list Directory Sync directories (read-only)
• kody:@kody/workos/list-directory-users — list users in one directory (read-only)
• kody:@kody/workos/list-events — list events by type (read-only)
• kody:@kody/workos/create-portal-link — Admin Portal setup link (dryRun / confirm)
• kody:@kody/workos/request — low-level WorkOS API escape hatch
• kody:@kody/workos/types — shared TypeScript types

Examples

import listOrganizations from 'kody:@kody/workos/list-organizations'

export default async function main() {
	return await listOrganizations({ limit: 20 })
}

import listConnections from 'kody:@kody/workos/list-connections'
import listDirectories from 'kody:@kody/workos/list-directories'

export default async function main() {
	const organizationId = 'org_01EXAMPLE'
	const [connections, directories] = await Promise.all([
		listConnections({ organizationId }),
		listDirectories({ organizationId }),
	])
	return { connections: connections.items, directories: directories.items }
}

import createPortalLink from 'kody:@kody/workos/create-portal-link'

export default async function main() {
	return await createPortalLink({
		organization: 'org_01EXAMPLE',
		intent: 'sso',
		dryRun: true,
	})
}

Notes

• REST base: https://api.workos.com
• List helpers return { items, pageInfo }. Get helpers return a slim resource.
• list-events requires events (WorkOS does not accept an unfiltered stream).
• Admin Portal intents: sso, dsync, audit_logs, log_streams, domain_verification, certificate_renewal.
• This package is not affiliated with or endorsed by WorkOS.

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
• API reference
• Organizations
• Users
• SSO connections
• Directory Sync
• Events
• Admin Portal