WorkOS
Manage WorkOS enterprise features — organizations, SSO connections, Directory Sync users and groups, the Admin Portal, user management and the unified event stream.
About
WorkOS ships in the w6w first-party pack. It declares 23 actions, 3 health checks, and the host runs its code in a sandbox that never sees the credential.
- App id
io.w6w.workos- Version
- 0.1.1
- Author
- w6w
- Licence
- MIT
- Categories
- Security & Identity · Developer Tools
Overview
WorkOS handles the enterprise features a B2B product has to ship before an enterprise will buy it — single sign-on, SCIM user provisioning, and audit logs — and this app manages that from a workflow: register customer organizations, list their SSO connections and connected SCIM directories, read the directory users and groups a customer’s system pushes, manage identities and organization memberships, invite or grant access directly, and mint an Admin Portal link so a customer’s own IT team can configure their SSO or SCIM without a shared screen and an engineer.
Two objects are easy to conflate and this app keeps them apart: a Directory User is a record synced from a customer’s identity provider describing someone who works there, while a User is an identity in your own product that can authenticate — the two link only when the person signs in. A provisioning workflow should read the event stream rather than a directory listing, since a deprovisioned user simply disappears from a listing with no signal, while the event stream carries an explicit deletion event to react to.
Audit log writes are append-only and require the event’s schema to already be registered in the dashboard; reading them back out is an export request polled to completion rather than a direct read. Domains added to an organization default to requiring DNS verification before they route SSO, rather than being trusted immediately, since asserting a domain as verified decides where an entire company’s staff get sent to log in.
Build with WorkOS
Three routes to the same 23 actions. The Workflow tab is generated from WorkOS's own manifest and carries its real ids, so it is copy-pasteable; the Code and CLI examples are the same call for any action on any app, so every app-specific value in them is a blank you fill in.
Write an audit log event
audit-log-event-create Record something in a customer's audit log, which WorkOS can stream to their own SIEM. Append-only — a wrong event cannot be edited or deleted.
Start an audit log export
audit-log-export-create Ask WorkOS to assemble a customer's audit log for a date range. There is no read endpoint — an export is how events come back, and it finishes asynchronously.
Get an audit log export
audit-log-export-get Whether an export has finished, and its download URL. The URL is a pre-signed link to a customer's complete audit trail — returned, never logged.
Get an SSO connection
connection-get One connection with its state and the email domains it routes. An active connection whose domains do not match the user's address is never reached.
List SSO connections
connection-list Each customer's link to their identity provider, and its state. A `draft` connection is a setup that was started and abandoned — invisible until somebody cannot log in.
List directory groups
directory-group-list The groups a customer pushes over SCIM — the natural source for role assignment. Map on the group id, since customers rename groups without telling anybody.
List directories
directory-list The SCIM directories customers have connected. Independent of SSO — a customer can have working sign-in and no provisioning at all.
Get a directory user
directory-user-get One person from a customer's directory, including the custom SCIM attributes a provisioning rule reads — whose names differ per customer.
List directory users
directory-user-list Who the customer's directory says works there now. A deprovisioned user just STOPS being listed — use `event-list` if you need to react to that.
List events
event-list The ordered stream of what changed — the only place a directory DELETION appears, since a removed user simply stops being listed.
Invite a user to an organization
invitation-send Email an invitation instead of granting access outright — the recipient proves they control the address before they get in. The safe counterpart to adding a membership.
Create an organization
organization-create Register a customer company. Domains default to `pending` verification deliberately — asserting one as verified decides where those email addresses get sent to log in.
Delete an organization
organization-delete Remove a customer with its SSO connection, directory, memberships and audit events. Irreversible, and it locks that customer's staff out.
Get an organization
organization-get One customer and its domains. A domain still `pending` verification does not route SSO, which is the usual cause of a setup that looks finished but does not work.
List organizations
organization-list The customer companies in this environment. Filter by verified domain to match a new signup's email against an enterprise account that already exists.
Add a user to an organization
organization-membership-create Grant a person access to a customer's account with a role — immediately, with no invitation step. Omitting the role grants the environment default, not nothing.
List organization memberships
organization-membership-list Who belongs to which customer, and with what role — the row an access review cares about. Pending invitations are listed alongside active members unless filtered.
Update an organization
organization-update Rename a customer or set its domains. Domains REPLACE the existing list — dropping a verified one stops SSO for everybody with an address at it, silently.
Create an Admin Portal link
portal-link-create Mint a hosted page where a customer's own IT admin configures their SSO or SCIM — which is how the setup happens without an engineer on a call. The link is a short-lived credential.
Create a user
user-create Create an identity that can sign in. Marking the email verified says you proved it — WorkOS links a later SSO login to a verified address.
Get a user
user-get One identity. `email_verified` decides whether password sign-in works, and `last_sign_in_at` is the honest answer to whether a seat is being used.
List users
user-list The identities that can authenticate — which is NOT the customer's directory. A directory user who has never signed in has no user record at all.
Update a user
user-update Correct a name or change verification. Setting verified false locks password sign-in without deleting the account — which is the useful direction.
A workflow step names the app and the action, and the editor fills in the
connection when you pick one. This is the Step shape from the
workflow spec, carrying WorkOS's real ids.
{
"manifestVersion": "2",
"name": "workos-example",
"steps": [
{
"id": "audit-log-event-create",
"uses": {
"app": "io.w6w.workos",
"action": "audit-log-event-create",
"connection": "conn_YOUR_CONNECTION_ID"
},
"with": {
"organizationId": "<organizationId>",
"action": "<action>",
"actorId": "<actorId>"
}
}
]
}Here are some of the things you can do
-
Write an audit log event
performaudit-log-event-create -
Start an audit log export
performaudit-log-export-create -
Get an audit log export
readaudit-log-export-get -
Get an SSO connection
readconnection-get -
List SSO connections
readconnection-list
+18 more actions available
Every app-specific value here is a blank you have to fill in. An
app action is reached through the connection that authenticates it, so the
address is a connection id, not the app id — and connections belong to your account,
so a public page cannot know yours. Create one for WorkOS, then fill in
the three blanks: conn_YOUR_CONNECTION_ID, the action key, and the
parameters that action declares. The call itself is real — the shape is transcribed
from the studio's own snippet builder, which prints the same kind of blanks — but
nothing in it is specific to WorkOS. The Workflow tab is where this app's
real ids are.
npm install @w6w/sdkyarn add @w6w/sdkpnpm add @w6w/sdkdeno add npm:@w6w/sdkimport { W6wClient, isActionRun } from "@w6w/sdk";
// Reads W6W_BASE_URL and W6W_TOKEN from the environment when omitted.
const client = new W6wClient();
const envelope = await client.run({
urn: "conn_YOUR_CONNECTION_ID",
action: "audit-log-event-create",
payload: {
organizationId: "<value>",
action: "<value>",
actorId: "<value>",
actorType: "<value>",
targetId: "<value>",
targetType: "<value>",
// occurredAt: "<value>",
// metadata: "<value>",
// version: "<value>",
},
});
if (isActionRun(envelope)) console.log(envelope.value);npm install -g @w6w/cliw6w run conn_YOUR_CONNECTION_ID --action audit-log-event-create --payload '{"organizationId":"<value>","action":"<value>","actorId":"<value>","actorType":"<value>","targetId":"<value>","targetType":"<value>"}'Give an AI agent WorkOS — without giving it WorkOS's credentials. One MCP endpoint exposes every app, function and workflow the caller is entitled to, as tools it can discover and run. Access is granted per team while we onboard.
One tool call{
"name": "w6w_invoke",
"arguments": {
"ref": "app:io.w6w.workos#audit-log-event-create",
"input": {
"organizationId": "<organizationId>",
"action": "<action>",
"actorId": "<actorId>"
}
}
}
Every tool names its target with a single ref. The
app: form above doesn't name a connection at all — the
host resolves which of the caller's WorkOS connections to sign
with, and refuses rather than guesses when the answer is ambiguous.
What the agent gets
Credentials it can't read
The token is attached host-side, at the moment of the call. It is never a tool argument, never in the model's context, and never in a transcript — so a prompt injection has nothing to exfiltrate.
A tool surface scoped to the caller
Tools are derived per end user from what that person has actually connected and is entitled to — not one shared bot identity carrying the union of everyone's access.
A durable workflow in one call
Multi-step work runs on the workflow engine and returns a run handle the agent can poll — retries, branching and state survive the conversation that started them.
Health-aware discovery
WorkOS's declared health checks are on the surface too, so an agent can tell "the vendor is down" from "your credential expired" before it burns a retry on either.
The MCP surface is part of the hosted platform. WorkOS itself is MIT, and the runtime that executes it is source-available (FSL).
Health checks
WorkOS declares its own checks, so its health is a property of the app rather than something the host guesses at.
WorkOS platform status
The API this app calls and the SSO and Directory Sync paths a customer's staff depend on — the second mattering whatever the workflow is doing at the time.
Environment and reachability
Which WorkOS environment this key belongs to, and how many organizations it can see — because a staging key doing production work fails silently rather than loudly.