Skip to content
← Public packages

@kody/workos

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

FollowFork

Files

AGENTS.md

91 lines · 3.2 KB · Markdown

@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

NamePurpose
workosApiKeyDefault 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

ExportImport
root dispatcher (default smoke-test)kody:@kody/workos
accountskody:@kody/workos/accounts
smoke-testkody:@kody/workos/smoke-test
list-organizationskody:@kody/workos/list-organizations
get-organizationkody:@kody/workos/get-organization
create-organizationkody:@kody/workos/create-organization
update-organizationkody:@kody/workos/update-organization
delete-organizationkody:@kody/workos/delete-organization
list-userskody:@kody/workos/list-users
get-userkody:@kody/workos/get-user
list-connectionskody:@kody/workos/list-connections
list-directorieskody:@kody/workos/list-directories
list-directory-userskody:@kody/workos/list-directory-users
list-eventskody:@kody/workos/list-events
create-portal-linkkody:@kody/workos/create-portal-link
requestkody:@kody/workos/request
typeskody:@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-events requires events (WorkOS rejects an unfiltered stream).
  • Admin Portal intents: sso, dsync, audit_logs, log_streams, domain_verification, certificate_renewal.
  • account: "work" → secret workosApiKey-work; or pass secretName.
  • Get helpers accept id, or externalId with lookup: "external".
  • After fork, save the caller's workosApiKey — do not treat live @kody/workos as a shared tenant. Keep dryRun / confirm guards.