Title: Integration with WorkOS
Author: Gustavo Bordoni
Published: अप्रैल 27, 2026
Last modified: मई 12, 2026
---
प्लगइन्स खोजें
# Integration with WorkOS
[Gustavo Bordoni](https://profiles.wordpress.org/bordoni/) द्वारा
[डाउनलोड](https://downloads.wordpress.org/plugin/integration-workos.1.0.3.zip)
* [विवरण](https://hi.wordpress.org/plugins/integration-workos/#description)
* [समीक्षा](https://hi.wordpress.org/plugins/integration-workos/#reviews)
* [स्थापना](https://hi.wordpress.org/plugins/integration-workos/#installation)
* [विकास](https://hi.wordpress.org/plugins/integration-workos/#developers)
[समर्थन](https://wordpress.org/support/plugin/integration-workos/)
## विवरण
Integration with WorkOS connects your WordPress site with [WorkOS](https://workos.com)
for enterprise-grade identity management.
#### Requirements
* WordPress 6.2 or higher
* PHP 7.4 or higher
* A [WorkOS](https://workos.com) account with API credentials
#### Custom AuthKit
* **WordPress-hosted React login** — no redirect to WorkOS for password, magic
code, signup, invitation, or MFA. Mounts on wp-login.php, a shortcode (`[workos:
login]`), and a dedicated `/workos/login/{profile}` route.
* **Login Profiles** — admin-defined presets (enabled sign-in methods, pinned organization,
signup/invite toggles, MFA policy, branding) edited from **WorkOS Login Profiles**.
The organization picker loads live from WorkOS so admins pick an org by name
instead of pasting raw IDs.
* **Per-profile custom URL paths** — assign any profile its own URL (e.g. `/members`,`/
team/login`) on top of the canonical `/workos/login/{profile}` rewrite. When
the default profile owns a custom path, `/wp-login.php` 302s to it (preserving
every inbound query arg). Reserved core paths can’t be claimed.
* **Already-signed-in handling** — visitors who hit any AuthKit surface while logged
in are 302’d to their post-login destination (or, in the shortcode, see an inline“
You’re already signed in” notice with a Continue link).
* **`forward_query_args` per-profile toggle** — opt-in passing of marketing/analytics
query args (`utm_*`, `ref`, etc.) onto the post-login destination. WP and plugin
internals are always stripped.
* **Sign-in methods** — email + password, magic code, social OAuth (Google, Microsoft,
GitHub, Apple), and passkey. Each profile chooses its own subset.
* **MFA** — TOTP, SMS, and WebAuthn/passkey with in-app enrollment + challenge.
Profile-level `mfa.enforce` (`never`/`if_required`/`always`) and factor allowlist
are applied at login time.
* **Self-serve sign-up + invitation acceptance + in-app password reset** — all
handled by the React shell; no third-party pages.
* **Branding controls** — per-profile heading, subheading, primary color (with
WordPress admin-color presets), and logo with a three-mode toggle (`default`
falls back to the Site Icon then a bundled WP logo, `custom` uses the chosen
image, `none` hides the logo).
* **Embed & URLs in the editor** — every Login Profile shows copyable input fields
for its canonical URL, optional custom-path URL, and shortcode so admins can
paste them into pages or share them with users.
* **WorkOS Radar** anti-fraud integration optional via `WORKOS_RADAR_SITE_KEY`.
* **Profile routing rules** — send incoming logins to a specific profile based
on `redirect_to`, referrer host, or user role.
#### Authentication
* **Single Sign-On (SSO)** — legacy AuthKit redirect mode, per-profile selectable
for SAML/OIDC connections.
* **Headless mode** — intercept WordPress’s `authenticate` filter for custom login
forms.
* **Legacy Login Button** — Gutenberg block and classic widget (AuthKit-redirect
flow).
* **Login Bypass** — Access the native WordPress login form via `?fallback=1` when
WorkOS is unavailable.
* **Password Reset Integration** — Redirect password reset to WorkOS or fall back
to WordPress.
* **Registration Redirect** — Redirect registration to WorkOS AuthKit.
* **REST API Authentication** — Verify WorkOS access tokens for headless/API usage.
#### User & Organization Management
* **Directory Sync** — Automatic user provisioning and deprovisioning via SCIM.
* **Role Mapping** — Map WorkOS organization roles to WordPress roles.
* **Organization Management** — Multi-tenant organization support.
* **Entitlement Gate** — Require organization membership to log in.
#### Redirects
* **Role-Based Login Redirects** — Send users to different URLs after login based
on their WordPress role.
* **Role-Based Logout Redirects** — Send users to different URLs after logout based
on their WordPress role.
#### Admin Tools
* **Activity Logging** — Local database table with admin viewer for tracking authentication
and sync events.
* **Audit Logging** — Forward WordPress events to WorkOS Audit Logs.
* **Diagnostics Page** — System health checks, configuration status, and connectivity
tests.
* **Onboarding Wizard** — Guided setup for initial plugin configuration and user
sync.
* **Admin Bar Badge** — Shows the active WorkOS environment in the admin bar.
* **WP-CLI Commands** — Full CLI access for scripting, bulk operations, and diagnostics.
#### Privacy & Security
This plugin transmits user data (email, name) to WorkOS for authentication and directory
sync. No data is sent until you configure API credentials and users authenticate.
API keys are stored in the WordPress database or can be defined as constants in
wp-config.php. See the “External services” section for full details on data transmitted.
### Support
* [Documentation & Source Code](https://github.com/bordoni/integration-workos)
* [Report a Bug](https://github.com/bordoni/integration-workos/issues)
* [WorkOS Documentation](https://workos.com/docs)
### External services
This plugin connects to the [WorkOS API](https://workos.com) (`https://api.workos.
com`) to provide enterprise identity management features for WordPress.
#### Authentication (SSO)
When a user logs in via WorkOS AuthKit or headless mode, the plugin sends an authorization
code (and, in headless mode, the user’s email and password) to WorkOS to exchange
for user identity data and access tokens. This happens each time a user authenticates
through WorkOS.
#### User Management
When the site administrator creates, updates, or syncs users between WordPress and
WorkOS, the plugin sends user profile data (email, first name, last name) to the
WorkOS API.
#### Directory Sync
The plugin receives incoming webhook requests from WorkOS containing directory and
user data for automatic provisioning and deprovisioning. The webhook endpoint URL
is registered with WorkOS by the site administrator.
#### Organization Management
When managing organizations, the plugin sends and retrieves organization data (name,
membership details, role assignments) to and from the WorkOS API.
#### Audit Logging
When audit logging is enabled, the plugin sends WordPress event data (action performed,
actor, target, and metadata) to the WorkOS Audit Logs API on each tracked event.
#### Token Verification
When REST API authentication is enabled, the plugin fetches JSON Web Key Sets (JWKS)
from WorkOS (`https://api.workos.com/sso/jwks/{client_id}`) to verify access tokens.
The JWKS response is cached locally for one hour.
#### Service links
WorkOS is provided by WorkOS, Inc.
* [Terms of Service](https://workos.com/legal/terms)
* [Privacy Policy](https://workos.com/legal/privacy)
## स्क्रीनशॉट्स
* [[
* Branded Custom AuthKit login shown to site visitors — driven by a Login Profile,
with logo, heading, brand color, and the sign-in methods (SSO, magic code, passkey,
password) you enable.
* [[
* Login Profiles editor — pick sign-in methods, pin an organization, set the MFA
policy, customize the URL path, and brand the card with a logo and color, all
without code.
* [[
* WorkOS settings — switch between Production and Staging, manage API credentials
and the webhook secret, and choose between Custom AuthKit and AuthKit Redirect
login modes.
* [[
* Role mapping and redirects — map WorkOS organization roles to WordPress roles,
route users to role-specific URLs after login and logout, and choose what happens
to deprovisioned users.
## ब्लॉकस
यह प्लगइन 1 ब्लॉक प्रदान करता है।
* WorkOS Login Button Display a WorkOS login or logout button.
## इंस्टॉलेशन
1. Go to **Plugins > Add New** in your WordPress admin and search for “Integration
with WorkOS”.
2. Click **Install Now**, then **Activate**.
3. Go to **Settings > WorkOS** and enter your API Key and Client ID from the [WorkOS Dashboard](https://dashboard.workos.com).
4. Configure your webhook endpoint in the WorkOS Dashboard using the URL shown on
the settings page.
5. (Optional) Run the Onboarding Wizard at **Settings > WorkOS > Onboarding** for
guided setup.
## सामान्य प्रश्न
### Where do I get my API credentials?
Sign up at [workos.com](https://workos.com) and find your API Key and Client ID
in the dashboard.
### Can users still log in with passwords?
Yes, if “Password Fallback” is enabled in settings. Users can access the standard
login form via `?fallback=1`.
### How do I add a login button to my site?
Add the “WorkOS Login” Gutenberg block or use the “WorkOS Login” classic widget.
Both render a styled login button that redirects to WorkOS AuthKit.
### How do I show the new WordPress-hosted login (Custom AuthKit) on a page?
Use `[workos:login profile="your-profile-slug"]` or link to `/workos/login/{profile}`.
Both mount the same React shell. The reserved `default` Login Profile automatically
takes over wp-login.php.
### Can different login pages offer different sign-in methods?
Yes. Each Login Profile (WorkOS Login Profiles) picks its own set of enabled methods(
password, magic code, any subset of social providers, passkey), pins an organization,
and sets its own MFA policy and branding. Reference a profile by slug in the shortcode
or URL.
### Can I host a Login Profile at a custom URL like `/members`?
Yes. Edit any profile and tick **Use a custom URL path**, then fill in the path (
e.g. `members` or `team/login`). The plugin registers an extra rewrite rule that
mounts the same React shell at `https://yoursite.com/members/`. The canonical `/
workos/login/{slug}` URL keeps working too. Reserved core paths (`wp-admin`, `wp-
includes`, `wp-content`, `wp-json`, `workos`, `feed`, etc.) are blocked at save
time. If you set a custom path on the **default** profile, `/wp-login.php?action
=login` 302s to it for everyone (with all `redirect_to` / `interim-login` / language/
nonce args preserved).
### What happens if WorkOS is down?
Users can bypass the WorkOS redirect by appending `?fallback=1` to the login URL(
e.g., `wp-login.php?fallback=1`). This loads the standard WordPress login form with
native password authentication.
### Can I require organization membership to log in?
Yes. The Entitlement Gate feature restricts login to users who belong to the configured
WorkOS organization. Users without a membership are denied access with a customizable
error message.
### How do I sync existing WordPress users to WorkOS?
Use the Onboarding Wizard (Settings > WorkOS > Onboarding) for a guided walkthrough,
or use the WP-CLI command `wp workos sync push` to bulk-push users to WorkOS.
### Does this plugin support WordPress multisite?
Yes. Organizations can be mapped to specific sites in a multisite network, and the
plugin stores organization-to-site mappings in a dedicated table.
### How do I run diagnostics?
Go to **Tools > WorkOS Diagnostics** in the WordPress admin. The diagnostics page
checks API connectivity, configuration completeness, database schema status, and
other health indicators.
## समीक्षाएं
इस प्लगइन के लिए कोई समीक्षा नहीं है।
## सहायक &डेवलपर्स
यह खुला स्रोत सॉफ्टवेयर है। अनुगामी लोगो ने इस प्लगइन के लिए योगदान दिया है।
योगदानकर्ता
* [ Gustavo Bordoni ](https://profiles.wordpress.org/bordoni/)
[Translate “Integration with WorkOS” into your language.](https://translate.wordpress.org/projects/wp-plugins/integration-workos)
### Interested in development?
[Browse the code](https://plugins.trac.wordpress.org/browser/integration-workos/),
check out the [SVN repository](https://plugins.svn.wordpress.org/integration-workos/),
or subscribe to the [development log](https://plugins.trac.wordpress.org/log/integration-workos/)
by [RSS](https://plugins.trac.wordpress.org/log/integration-workos/?limit=100&mode=stop_on_copy&format=rss).
## बदलाव विवरण
#### 1.0.3 – 2026-05-12
* Fix: AuthKit login flows now recover transparently from WorkOS `organization_selection_required`.
When the Login Profile has an organization pinned (with `Config::get_organization_id()`
as a fallback), the plugin re-authenticates via the `organization-selection`
grant instead of surfacing “The user must choose an organization to finish their
authentication.” to the user.
* Fix: pre-existing WordPress users who joined before an organization was pinned
are now auto-enrolled into the pinned WorkOS organization. The plugin creates
the WorkOS membership and retries the authenticate call when (and only when)
a matching local WP user exists and the WorkOS error body carries the authenticated`
user_id`. Membership creation and the `entity_already_exists` short-circuit are
logged via `workos_log()` (visible under `WP_DEBUG` / `WORKOS_DEBUG`). Strangers
and ambiguous lookups still get a clean `pinned_org_mismatch` error — no email-
lookup guessing.
* Fix: the legacy OAuth callback at `/workos/callback` now routes through `LoginCompleter`,
so it shares the same `organization_selection_required` recovery, MFA gating,
and post-login bookkeeping as the AuthKit REST endpoints. The callback no longer
short-circuits on the WorkOS error and discards the OAuth code. Legacy AuthKit-
redirect callbacks (no profile slug in `state`) keep their original redirect
contract — the state-supplied `redirect_to` still wins over the default profile’s`
post_login_redirect`.
#### 1.0.2 – 2026-05-11
* New: WordPress password fallback — if WorkOS rejects a password, the auth endpoint
can retry against WordPress’s own `wp_authenticate()` to cover users whose passwords
were never synced to WorkOS, then link the user to WorkOS and (by default) write
the password through so future logins authenticate directly. A new “Require Email
Confirmation on Fallback” setting switches the post-fallback step to a magic-
code email instead of syncing the plaintext password. Gated by the existing `
allow_password_fallback` toggle.
* New: wp-config.php constant seeder — defining `WORKOS_*` (or env-scoped `WORKOS_{
PRODUCTION|STAGING}_*`) constants now seeds those values into the database on
boot, so the admin UI reflects them. Covers string credentials, the new boolean
toggles, and `WORKOS_REDIRECT_URLS` arrays. Hash-skipped when nothing has changed—
one autoloaded option read per request in steady state.
* Fix: Auth REST endpoints under `/wp-json/workos/v1/auth/*` now read the nonce
from `X-WorkOS-Nonce` instead of `X-WP-Nonce` to avoid a header collision with
WordPress core and other plugins. The bundled React shell is updated; external
clients hitting these endpoints directly must rename the header.
#### 1.0.1 – 2026-05-01
* New: Organization tab — manual Refresh button next to the organization dropdown
re-fetches organizations from WorkOS on demand via the admin REST endpoint (no
admin-ajax), bypassing the 5-minute cache. The dropdown is blocked with a spinner
during the refresh and the selected organization is preserved when it still exists.
* New: `?refresh=1` query parameter on `GET /wp-json/workos/v1/admin/profiles/organizations`
to drop the shared transient before fetching.
* Fix: Organization tab — “Save Settings” was blocked by a hidden, required `org_name`
input. The Create Organization modal is now rendered at `admin_footer` so its
inner `