WorkOS

WorkOS

This connector uses the WorkOS API (https://api.workos.com) of one WorkOS environment: organizations and their domains, AuthKit (User Management) users, organization memberships, invitations and sessions, SSO connections, Directory Sync directories with their users and groups, Audit Logs, the event stream, and RBAC roles and permissions. It can create and update organizations, domains, users, memberships and invitations and trigger a directory sync. It does not configure SSO connections, AuthKit branding, redirect URIs, Vault, Pipes or API keys, and it never signs anyone in.

Setup (2 minutes)

1. Open https://dashboard.workos.com, pick the environment (Sandbox or Production) in the top bar and open API Keys.
2. Create a secret key (sk_...) and paste it into WORKOS_API_KEY. The key is shown once.
3. Run workos_list_organizations to check it. A key belongs to one environment and has full access to that environment's API: there are no scopes. Start with a Sandbox key; use a Production key only when the AI should work on real data.

What the AI sees: personal and sensitive data This key reaches the identity data of every customer organization in the environment, and the AI reads whatever a tool returns: user names and email addresses, sign-in identities, session IP addresses and user agents, directory users with job titles and the provider's raw attributes (workos_get_directory_user and workos_get_directory_group return them in full; they can hold phone numbers, manager, department and employee ids), organization metadata and Stripe customer ids, and audit log content. Share only what the task needs.

• Secret values: the connector never returns the API key. Invitation answers have their token and accept_invitation_url removed, because that link lets anyone who has it join the organization. workos_get_audit_log_export returns a short-lived download link (url) to the CSV; treat it like a password and do not paste it into other places.
• WorkOS also runs an official MCP server (https://mcp.workos.com/mcp, OAuth as your dashboard user); this connector instead uses an API key and needs no dashboard login.

Workflow

• Organizations: workos_list_organizations (filter search or domains), workos_get_organization, workos_get_organization_by_external_id, workos_create_organization, workos_update_organization.
• Domains: workos_create_organization_domain adds one as pending with a DNS TXT record (verification_prefix, verification_token) for the domain owner to publish; then workos_verify_organization_domain and workos_get_organization_domain for the state. Domain ids are in the domains array of an organization.
• Users: workos_list_users (by email or organization_id), workos_get_user, workos_get_user_by_external_id, workos_create_user, workos_update_user; sign-in providers with workos_list_user_identities; devices with workos_list_user_sessions.
• Memberships and roles: workos_list_organization_memberships (by organization_id and/or user_id, statuses), workos_get_organization_membership, workos_create_organization_membership, workos_update_organization_membership to change the role, workos_deactivate_organization_membership and workos_reactivate_organization_membership to block and restore access. Role slugs come from workos_list_roles, workos_get_role and workos_list_organization_roles (custom roles start with org-); permissions from workos_list_permissions.
• Invitations: workos_list_invitations, workos_get_invitation, workos_send_invitation (WorkOS sends the email), workos_resend_invitation.
• SSO: workos_list_connections and workos_get_connection show type and state (active means users can sign in).
• Directory Sync: workos_list_directories, workos_get_directory, workos_list_directory_users (needs directory or group), workos_get_directory_user, workos_list_directory_groups (needs directory or user), workos_get_directory_group; workos_sync_directory queues a sync now.
• Audit Logs: workos_list_audit_log_actions and workos_list_audit_log_schemas for what is logged; workos_create_audit_log_export for a range, then workos_get_audit_log_export until state is ready; workos_get_audit_log_retention for how long events are kept. workos_create_audit_log_event writes an event.
• What changed: workos_list_events with events (comma-separated types such as user.created, organization_membership.updated, dsync.user.created, connection.activated) and range_start / range_end, order: asc to replay them in sequence. The API keeps 90 days of events; one call covers at most 30 days.

Switched off at install: workos_delete_organization, workos_delete_organization_domain, workos_delete_user, workos_delete_organization_membership, workos_revoke_invitation, workos_revoke_session and workos_create_audit_log_event; they cannot be undone (audit log events cannot be removed once written), so an admin switches them on when the team needs them.

Reading the answers: ids carry a type prefix (org_, org_domain_, user_, om_, invitation_, session_, conn_, directory_, directory_user_, directory_group_, audit_log_export_, event_). Timestamps are ISO 8601 in UTC. Lists come as {"object": "list", "data": [...], "list_metadata": {"before": ..., "after": ...}}. metadata values are strings.

Paging: lists return 10 items by default, up to 100 with limit, newest first. For the next page pass list_metadata.after as after; stop when it is null. workos_list_events pages the same way.

Updates: workos_update_organization and workos_update_user change only the fields you pass; domain_data and metadata replace the stored value, so send the full list or object.

Limits: 6,000 requests a minute per key; AuthKit 1,000 reads and 500 writes per 10 seconds; directory users 4 requests a second per directory; organization deletes 50 a minute. Invitation emails count toward WorkOS's email sending limits.

Errors: 401 wrong or revoked key, 403 the key may not do this or the feature is not enabled, 404 unknown id (or an id from another environment), 400 or 422 an invalid field (the body names it), 429 rate limit: wait and retry once.