{"id":"workos","kind":"sdk","name":"WorkOS","slug":"workos","description":"Enterprise-ready auth: SSO, Directory Sync, and Audit Logs.","vendor":"WorkOS","languages":["typescript","nodejs","javascript","python","go","ruby","php","java","kotlin"],"categories":["auth"],"homepage":"https://workos.com","docsUrl":"https://workos.com/docs","githubUrl":"https://github.com/workos","tags":["sso","enterprise"],"packages":[{"registry":"npm","name":"@workos-inc/node","url":"https://www.npmjs.com/package/@workos-inc/node"},{"registry":"pypi","name":"workos","url":"https://pypi.org/project/workos/"}],"skills":[{"name":"workos","url":"https://skills.sh/workos/skills/workos","install":"npx skills add workos/skills --skill workos","sdk":"workos","key":"workos/workos","description":"Use when the user asks for a WorkOS docs URL, term, or dashboard field (Sign-in endpoint, initiate_login_uri, Redirect URI, `WORKOS_*` env vars), or is implementing, debugging, or migrating WorkOS — AuthKit, SSO/SAML, Directory Sync, RBAC, FGA, MFA, Vault, Audit Logs, Admin Portal, Pipes (Connected Apps), Feature Flags, Radar (bot/fraud detection), webhooks, Custom Domains, running the `workos` CLI in agent or sandbox sessions (`WORKOS_MODE`, `workos doctor`), or migrating from Auth0, Clerk, Cognito, Firebase, Supabase, Stytch, Descope, or Better Auth. Also triggers on @workos-inc/* imports.","hasContent":true,"content":"---\nname: workos\ndescription: Use when the user asks for a WorkOS docs URL, term, or dashboard field (Sign-in endpoint, initiate_login_uri, Redirect URI, `WORKOS_*` env vars), or is implementing, debugging, or migrating WorkOS — AuthKit, SSO/SAML, Directory Sync, RBAC, FGA, MFA, Vault, Audit Logs, Admin Portal, Pipes (Connected Apps), Feature Flags, Radar (bot/fraud detection), webhooks, Custom Domains, running the `workos` CLI in agent or sandbox sessions (`WORKOS_MODE`, `workos doctor`), or migrating from Auth0, Clerk, Cognito, Firebase, Supabase, Stytch, Descope, or Better Auth. Also triggers on @workos-inc/* imports.\n---\n\n# WorkOS Skill Router\n\n## How to Use\n\n**This file is a router, NOT the answer.** Before responding to the user:\n\n1. Match the request to a reference file using Rule 0 and the decision tree below.\n2. **You MUST Read the matched reference file with the Read tool before producing any answer, URL, or code.** If you have not Read a reference, you have not followed this skill.\n3. Follow the instructions inside the reference (it will tell you which live docs to fetch with WebFetch and which gotchas to avoid).\n\n**Exception**: Widget requests use the `workos-widgets` skill via the Skill tool — it has its own multi-framework orchestration.\n\n## Guardrails (apply to every response)\n\nThese apply regardless of which routing rule fires. They exist because the most common failure mode of past WorkOS agent interactions has been plausibly-shaped fabrication of CLI commands and Dashboard paths.\n\n- **Check for the WorkOS MCP server before reaching for the CLI on workspace-management tasks.** If the session has WorkOS MCP tools connected (a server exposing `whoami`, `list_operations`, `query`, and `mutate` — tool names may carry a client-specific prefix), prefer those tools for reading and changing workspace resources: they already run as the signed-in dashboard user, with no CLI install and no API key. The CLI remains the right surface for bootstrap, seeding, local project config, and diagnostics. The full decision guide is the \"Choosing a surface\" section of `references/workos-management.md`.\n- **Never invent `workos` CLI commands.** If the user asks about CLI support or you're about to suggest a command, verify the command tree first. The authoritative source is `WORKOS_MODE=agent workos --help --json` — it emits the complete registered command tree. Do not assume a `create` subcommand exists because `list`/`get`/`delete` do. See `references/workos-management.md`.\n- **Prefer `WORKOS_MODE=agent` when invoking the `workos` CLI from a coding-agent session.** The CLI auto-detects most agent environments (`CLAUDECODE`, `CLAUDE_CODE`, `CURSOR_AGENT`, `CODEX_SANDBOX`, non-TTY), but the explicit env var is more reliable across sandbox configurations. See the **WorkOS CLI in Coding-Agent Sessions** section below.\n- **Never invent Dashboard click-paths.** Phrases like \"Dashboard > Organizations > X > Roles > Map Groups\" or `dashboard.workos.com/some/specific/path` should not appear unless you have verified them against a docs page you just fetched. The Dashboard UI reorganizes; docs pages are stable. Cite the docs URL and describe the destination conceptually (\"the Authorization page\", \"the directory's settings\") instead of committing to a click-path.\n- **When the user wants to do something not supported by the CLI, say so plainly.** Users are better served by \"this isn't in the CLI; here's the docs URL for how to do it\" than by a fabricated command that fails. See the \"Not in the CLI\" section of `references/workos-management.md`.\n- **Prefer docs URLs over prose when writing recipes.** If a reference file tells you to cite a specific docs URL, cite it literally; don't paraphrase the URL's slug.\n\n## WorkOS CLI in Coding-Agent Sessions\n\nThe CLI resolves two independent axes: **interaction mode** (`human`/`agent`/`ci`) and **output mode** (`human`/`json`). The CLI auto-detects agent environments via known env vars (`CLAUDECODE`, `CLAUDE_CODE`, `CURSOR_AGENT`, `CODEX_SANDBOX`, `CURSOR_TRACE_ID`) and non-TTY detection, but explicit settings are more reliable across sandbox configurations.\n\n**Recommended preflight for any setup or debugging task:**\n\n```bash\nWORKOS_MODE=agent workos doctor --json --skip-ai\n```\n\n`--skip-ai` disables the doctor's AI-powered diagnosis pass, which requires an API key and network round-trip — neither is guaranteed in a sandbox. If `--skip-ai` errors as an unknown flag, the CLI is outdated — see `references/workos-cli-upgrade.md`. The structured JSON output is sufficient for programmatic triage.\n\nThis returns a structured JSON report with `interactionMode` (`{ mode, source }`) and `hostExecution` (`{ ok, failures[] }`) fields. Read the JSON before suggesting fixes.\n\n**Rules:**\n\n- Use `--json` when parsing command output. It controls **formatting only** — it does not change CLI behavior.\n- Use `WORKOS_MODE=agent` even when relaying human-readable messages. It controls **prompts, browser launch, and host trust**.\n- Treat the doctor `HOST_EXECUTION_UNTRUSTED` issue as a hard trust boundary. If the doctor report contains this issue (or `hostExecution.ok` is `false`), **the current shell may be sandboxed**. Auth, config, keychain, and API failures from this shell are not authoritative. Ask the user to re-run host-sensitive commands (`workos auth login`, `workos doctor`, `workos env add`) on their host shell before drawing conclusions.\n- Do not assume browser-based auth (`workos auth login`) works in a sandbox. If auth is required, surface the manual URL/code fallback that the CLI prints, or ask the user to run `workos auth login` on their host shell.\n- For destructive CLI commands in agent mode, pass the explicit confirmation flag. Agent mode never prompts, so omitting the flag causes a `confirmation_required` error. Known flags: `--yes` for `workos api` (mutating methods), `--force` for `workos connection delete`, `workos directory delete`, and `workos debug reset`. If unsure which flag a command expects, run `workos <cmd> --help --json` to check.\n- Structured CLI errors (JSON on stderr) include an optional `error.recovery.hints` array, where each hint has `description`, optional `command`, and optional `hostShellRequired`. Prefer those hints over guessing the next step.\n\n**Legacy compatibility you may encounter:**\n\n- `WORKOS_NO_PROMPT=1` is a legacy alias that sets both agent interaction behavior AND JSON output. To migrate, set `WORKOS_MODE=agent` and pass `--json` to the command to preserve both behaviors. Using `WORKOS_MODE=agent` alone drops the implicit JSON formatting.\n- `WORKOS_FORCE_TTY=1` only affects output formatting; it does not change interaction mode.\n\n## Topic → Reference Map\n\n> Terminology lookups — \"what is X\", \"docs URL for X\" — are handled by **Rule 0** below, not this topic map. They route to `references/workos-terms.md`.\n\n### AuthKit Installation (Read `references/{name}.md`)\n\n| User wants to...                    | Read file                                     |\n| ----------------------------------- | --------------------------------------------- |\n| Install AuthKit in Next.js          | `references/workos-authkit-nextjs.md`         |\n| Install AuthKit in React SPA        | `references/workos-authkit-react.md`          |\n| Install AuthKit with React Router   | `references/workos-authkit-react-router.md`   |\n| Install AuthKit with TanStack Start | `references/workos-authkit-tanstack-start.md` |\n| Install AuthKit with SvelteKit      | `references/workos-authkit-sveltekit.md`      |\n| Install AuthKit in vanilla JS       | `references/workos-authkit-vanilla-js.md`     |\n| AuthKit architecture reference      | `references/workos-authkit-base.md`           |\n| Add WorkOS Widgets                  | Load `workos-widgets` skill via Skill tool    |\n\n### Backend SDK Installation (Read `references/{name}.md`)\n\n| User wants to...                   | Read file                          |\n| ---------------------------------- | ---------------------------------- |\n| Install AuthKit in Node.js backend | `references/workos-node.md`        |\n| Install AuthKit in Python          | `references/workos-python.md`      |\n| Install AuthKit in .NET            | `references/workos-dotnet.md`      |\n| Install AuthKit in Go              | `references/workos-go.md`          |\n| Install AuthKit in Ruby            | `references/workos-ruby.md`        |\n| Install AuthKit in PHP             | `references/workos-php.md`         |\n| Install AuthKit in PHP Laravel     | `references/workos-php-laravel.md` |\n| Install AuthKit in Kotlin          | `references/workos-kotlin.md`      |\n| Install AuthKit in Elixir          | `references/workos-elixir.md`      |\n\n### Features (Read `references/{name}.md`)\n\n| User wants to...                   | Read file                             |\n| ---------------------------------- | ------------------------------------- |\n| Configure Single Sign-On           | `references/workos-sso.md`            |\n| Set up Directory Sync              | `references/workos-directory-sync.md` |\n| Implement RBAC / roles             | `references/workos-rbac.md`           |\n| Encrypt data with Vault            | `references/workos-vault.md`          |\n| Handle WorkOS Events / webhooks    | `references/workos-events.md`         |\n| Set up Audit Logs                  | `references/workos-audit-logs.md`     |\n| Enable Admin Portal                | `references/workos-admin-portal.md`   |\n| Add Multi-Factor Auth              | `references/workos-mfa.md`            |\n| Configure email delivery           | `references/workos-email.md`          |\n| Set up Custom Domains              | `references/workos-custom-domains.md` |\n| Set up IdP integration             | `references/workos-integrations.md`   |\n| Implement FGA / fine-grained authz | `references/workos-fga.md`            |\n| Set up Pipes / Connected Apps      | `references/workos-pipes.md`          |\n| Configure Feature Flags            | `references/workos-feature-flags.md`  |\n| Set up Radar / fraud detection     | `references/workos-radar.md`          |\n\n### API References (Read `references/{name}.md`)\n\nFeature topic files above include endpoint tables for their respective APIs. Use these API-only references when no feature topic exists:\n\n| User wants to...           | Read file                               |\n| -------------------------- | --------------------------------------- |\n| AuthKit API Reference      | `references/workos-api-authkit.md`      |\n| Organization API Reference | `references/workos-api-organization.md` |\n\n### Migrations (Read `references/{name}.md`)\n\n| User wants to...                    | Read file                                             |\n| ----------------------------------- | ----------------------------------------------------- |\n| Migrate from Auth0                  | `references/workos-migrate-auth0.md`                  |\n| Migrate from AWS Cognito            | `references/workos-migrate-aws-cognito.md`            |\n| Migrate from Better Auth            | `references/workos-migrate-better-auth.md`            |\n| Migrate from Clerk                  | `references/workos-migrate-clerk.md`                  |\n| Migrate from Descope                | `references/workos-migrate-descope.md`                |\n| Migrate from Firebase               | `references/workos-migrate-firebase.md`               |\n| Migrate from Stytch                 | `references/workos-migrate-stytch.md`                 |\n| Migrate from Supabase Auth          | `references/workos-migrate-supabase-auth.md`          |\n| Migrate from the standalone SSO API | `references/workos-migrate-the-standalone-sso-api.md` |\n| Migrate from other services         | `references/workos-migrate-other-services.md`         |\n\n### Management & CLI Lifecycle (Read `references/{name}.md`)\n\n| User wants to...                                 | Read file                          |\n| ------------------------------------------------ | ---------------------------------- |\n| Manage WorkOS resources (MCP server or CLI)      | `references/workos-management.md`  |\n| Upgrade the `workos` CLI to a newer version      | `references/workos-cli-upgrade.md` |\n\n## Routing Decision Tree\n\nApply these rules in order. First match wins.\n\n### 0. Terminology / Docs URL Lookup\n\n**Triggers**: Lookup-shaped phrasing — \"what is X\", \"what does X mean\", \"docs URL for X\", \"where's the docs on X\", \"canonical link for X\", \"where do I configure X in the dashboard\" — where X is a WorkOS-specific config field, endpoint, env var, or term. Examples: `initiate_login_uri`, \"Sign-in endpoint\", \"Redirect URI\", dashboard field names, `WORKOS_*` environment variables.\n\n**Do NOT fire Rule 0** for setup-shaped phrasing like \"set up Vault\", \"enable Admin Portal\", \"configure MFA\" — those route to Rule 3 (Feature-Specific).\n\n**Action**:\n\n1. Read `references/workos-terms.md` — a curated table mapping WorkOS terms to canonical docs URLs.\n2. If the term is in the table, use the summary to answer; WebFetch the listed URL only if the user wants more detail.\n3. If the term is NOT in the table, follow the \"Still not here?\" fallback at the bottom of that file. When you find the canonical URL, answer the user and suggest they open a PR to add a row.\n\n**For terminology lookups**, do NOT WebFetch `llms.txt` or guess `workos.com/docs/...` URLs before reading the terms file. (Rules 7 and 8 use `llms.txt` for different purposes — this prohibition is scoped to Rule 0 only.)\n\n**Why this wins**: Terminology lookups happen independent of feature/framework/migration context. They need to short-circuit routing, not fall through to \"Vague or General\" (Rule 7).\n\n---\n\n### 1. Migration Context\n\n**Triggers**: User mentions migrating FROM another provider (Auth0, Clerk, Cognito, Firebase, Supabase, Stytch, Descope, Better Auth, standalone SSO API).\n\n**Action**: Read `references/workos-migrate-[provider].md` where `[provider]` matches the source system. If provider is not in the table, read `references/workos-migrate-other-services.md`.\n\n**Why this wins**: Migration context overrides feature-specific routing because users need provider-specific data export and transformation steps.\n\n---\n\n### 2. API Reference Request\n\n**Triggers**: User explicitly asks about \"API endpoints\", \"request format\", \"response schema\", \"API reference\", or mentions inspecting HTTP details.\n\n**Action**: For features with topic files (SSO, Directory Sync, RBAC, Vault, Events, Audit Logs, Admin Portal), read the feature topic file — it includes an endpoint table. For AuthKit or Organization APIs, read `references/workos-api-[domain].md`.\n\n**Why this wins**: API references are low-level; feature topics are high-level but include endpoint tables for quick reference.\n\n---\n\n### 3. Feature-Specific Request\n\n**Triggers**: User mentions a specific WorkOS feature by name (SSO, MFA, Directory Sync, Audit Logs, Vault, RBAC, FGA, Admin Portal, Custom Domains, Events, Integrations, Email, Pipes, Feature Flags, Radar).\n\n**Action**: Read `references/workos-[feature].md` where `[feature]` is the lowercase slug (sso, mfa, directory-sync, audit-logs, vault, rbac, fga, admin-portal, custom-domains, events, integrations, email, pipes, feature-flags, radar).\n\n**Exception**: Widget requests load the `workos-widgets` skill via the Skill tool — it has its own orchestration.\n\n**Disambiguation**: If user mentions BOTH a feature and \"API\", route to the feature topic file (it includes endpoints). If they mention MULTIPLE features, route to the MOST SPECIFIC one first (e.g., \"SSO with MFA\" → route to SSO; user can request MFA separately). If user mentions \"FGA\" or \"fine-grained authorization\", route to `workos-fga` — NOT `workos-rbac`. RBAC is org-level roles; FGA is resource-scoped roles on top of RBAC.\n\n**Special case — IdP group → role mapping**: If the user asks about mapping Entra / Azure AD / Okta / Google Workspace / SCIM / directory / SSO groups to WorkOS roles (regardless of exact phrasing), read BOTH `workos-rbac.md` AND the source-specific reference:\n\n- Directory Sync / SCIM / Google Workspace groups → also read `workos-directory-sync.md`\n- SSO-only groups → also read `workos-sso.md`\n\nBoth files now have a canonical recipe. Do not answer from memory or paraphrase dashboard menu paths — the docs don't commit to exact click-paths, so neither should you. This mapping is **not** a WorkOS CLI operation; if asked for a CLI command, state that it's not in the CLI and link the docs.\n\n---\n\n### 4. AuthKit Installation\n\n**Triggers**: User mentions authentication setup, login flow, sign-up, session management, or explicitly says \"AuthKit\" WITHOUT mentioning a specific feature like SSO or MFA.\n\n**Action**: Detect framework and language using the priority-ordered checks below. Read the corresponding reference file.\n\n**Disambiguation**:\n\n- If user says \"SSO login via AuthKit\", route to `workos-sso` (#3) — feature wins over framework.\n- If user says \"React login with Google\", route to AuthKit React (#4) — this is AuthKit-level auth, not SSO API.\n- If user is ALREADY using AuthKit and wants to add a feature (e.g., \"add MFA to my AuthKit app\"), route to the feature reference (#3), not back to AuthKit installation.\n\n#### Framework Detection Priority (AuthKit only)\n\nCheck in this exact order. First match wins:\n\n```\n1. `@tanstack/start` in package.json dependencies\n   → Read: references/workos-authkit-tanstack-start.md\n\n2. `@sveltejs/kit` in package.json dependencies\n   → Read: references/workos-authkit-sveltekit.md\n\n3. `react-router` or `react-router-dom` in package.json dependencies\n   → Read: references/workos-authkit-react-router.md\n\n4. `next.config.js` OR `next.config.mjs` OR `next.config.ts` exists in project root\n   → Read: references/workos-authkit-nextjs.md\n\n5. (`vite.config.js` OR `vite.config.ts` exists) AND `react` in package.json dependencies\n   → Read: references/workos-authkit-react.md\n\n6. NONE of the above detected\n   → Read: references/workos-authkit-vanilla-js.md\n```\n\n#### Language Detection (Backend SDKs)\n\nIf the project is NOT a JavaScript/TypeScript frontend framework, check:\n\n```\n1. `pyproject.toml` OR `requirements.txt` OR `setup.py` exists\n   → Read: references/workos-python.md\n\n2. `go.mod` exists\n   → Read: references/workos-go.md\n\n3. `Gemfile` exists OR `config/routes.rb` exists\n   → Read: references/workos-ruby.md\n\n4. `composer.json` exists AND `laravel/framework` in dependencies\n   → Read: references/workos-php-laravel.md\n\n5. `composer.json` exists (without Laravel)\n   → Read: references/workos-php.md\n\n6. `*.csproj` OR `*.sln` exists\n   → Read: references/workos-dotnet.md\n\n7. `build.gradle.kts` OR `build.gradle` exists\n   → Read: references/workos-kotlin.md\n\n8. `mix.exs` exists\n   → Read: references/workos-elixir.md\n\n9. `package.json` exists with `express` / `fastify` / `hono` / `koa` (backend JS)\n   → Read: references/workos-node.md\n```\n\n**Why this order**: TanStack, SvelteKit, and React Router are MORE specific than Next.js/Vite+React. A project can have both Next.js AND React Router; in that case, React Router wins because it's more specific. Vanilla JS is the fallback when no framework is detected. Backend languages are checked when no frontend framework is found.\n\n**Edge case — multiple frameworks detected**: If you detect conflicting signals (e.g., both `next.config.js` and `@tanstack/start`), ASK the user which one they want to use. Do NOT guess.\n\n**Edge case — framework unclear from context**: If the user says \"add login\" but you cannot scan files (remote repo, no access), ASK: \"Which framework/language are you using?\" Do NOT default without confirmation.\n\n---\n\n### 5. Integration Setup\n\n**Triggers**: User mentions connecting to external IdPs, configuring third-party integrations, or asks \"how do I integrate with [provider]\".\n\n**Action**: Read `references/workos-integrations.md`.\n\n**Why separate from SSO**: SSO covers the authentication flow; Integrations covers IdP configuration and connection setup. If user mentions BOTH (\"set up Google SSO\"), route to SSO (#3) — it will reference Integrations where needed.\n\n---\n\n### 6. Management Operations (MCP server or CLI)\n\n**Triggers**: User mentions managing WorkOS resources (organizations, users, roles, permissions), seeding data, or CLI management commands.\n\n**Action**: Read `references/workos-management.md`. It opens with a surface-choice guide: prefer connected WorkOS MCP tools for workspace reads/writes, and the CLI for bootstrap, seeding, local config, CI, and diagnostics. Read it even when MCP tools are present — it maps which operations live on which surface.\n\n**Sub-case — CLI upgrade**: If the user reports an outdated `workos` CLI (`workos --version` shows an old release, `unknown command` errors after following recent docs, or asks \"how do I update the workos CLI?\"), read `references/workos-cli-upgrade.md` instead. Do NOT guess the latest version — that file tells you to instruct the user to run `npm view workos version`.\n\n---\n\n### 7. Vague or General Request\n\n**Triggers**: User says \"help with WorkOS\", \"WorkOS setup\", \"what can WorkOS do\", or provides no feature-specific context.\n\n**Action**:\n\n1. WebFetch https://workos.com/docs/llms.txt\n2. Scan the index for the section that best matches the user's likely intent\n3. WebFetch the specific section URL\n4. Summarize capabilities and ASK the user what they want to accomplish\n\n**Do NOT guess a feature** — force disambiguation by showing options.\n\n---\n\n### 8. No Match / Ambiguous\n\n**Triggers**: None of the above rules match, OR the request is genuinely ambiguous.\n\n**Action**:\n\n1. WebFetch https://workos.com/docs/llms.txt\n2. Search the index for keywords from the user's request\n3. If you find a match, WebFetch that section URL and proceed\n4. If NO match, respond: \"I couldn't find a WorkOS feature matching '[user's term]'. Could you clarify? For example: authentication, SSO, MFA, directory sync, audit logs, etc.\"\n\n---\n\n## Edge Cases\n\n### User mentions multiple features\n\nRoute to the MOST SPECIFIC reference first. Example: \"SSO with MFA and directory sync\" → route to `workos-sso` first. After completing SSO setup, the user can request MFA and Directory Sync separately.\n\n### User mentions a feature + API reference\n\nRoute to the feature topic file — it includes an endpoint table. Example: \"SSO API endpoints\" → `workos-sso.md`.\n\n### User wants to ADD a feature to an existing AuthKit setup\n\nRoute to the feature reference (#3), not back to AuthKit installation. Example: \"I'm using AuthKit in Next.js and want to add SSO\" → `workos-sso.md`.\n\n### User mentions a provider but no feature\n\nRoute to Integrations (#5). Example: \"How do I connect Okta?\" → `workos-integrations.md`.\n\n### User mentions a provider AND a feature\n\nRoute to the feature reference (#3). Example: \"Set up Okta SSO\" → `workos-sso.md` (it will reference Integrations for Okta setup).\n\n### Unknown framework for AuthKit\n\nIf you cannot detect framework and the user hasn't specified, ASK: \"Which framework/language are you using?\" Do NOT default without confirmation.\n\n### Framework conflicts (multiple frameworks detected)\n\nIf detection finds conflicting signals (e.g., both Next.js and TanStack Start configs), ASK: \"I see both [framework A] and [framework B]. Which one do you want to use for AuthKit?\"\n\n### User provides no context at all\n\nFollow step #7 (Vague or General Request): fetch llms.txt, show options, and force disambiguation.\n","contentSource":"https://raw.githubusercontent.com/workos/skills/main/plugins/workos/skills/workos/SKILL.md","contentFetchedAt":"2026-07-27T09:02:27.723Z"}],"official":true,"generatedAt":"2026-07-27T09:02:29.956Z"}