Docs

When AuthKit is enabled on your account, sign-in goes through WorkOS. The tenant ↔ WorkOS Organization mirror, the sign-in path, invite acceptance, and the failure modes a tenant admin can hit.

SSO with WorkOS

When AuthKit is enabled for your account, sign-in goes through a WorkOS-hosted page. This page is for the tenant admin — when AuthKit is on, what your team sees and how the FastYoke side mirrors the WorkOS side.

If AuthKit is not enabled, your team uses the local + OTP paths in Sign-in flows instead. Enabling AuthKit is an operator action — see the operator runbook at the bottom of this page.

The tenant ↔ WorkOS Organization mirror

Every FastYoke tenant with AuthKit enabled maps 1:1 to a WorkOS Organization. The platform sets up the mirror on first sign-in; tenant admins don't manage the WorkOS side directly.

A consequence: changes that affect membership (invites, removals) take effect on both sides. The platform writes through to WorkOS on accept/remove so the two never drift.

The sign-in path

  1. A user opens the FastYoke sign-in page.
  2. The page calls GET /auth/authkit/signin, which redirects to a WorkOS-hosted page.
  3. WorkOS authenticates the user against whatever identity provider is wired to the Organization (Okta, Google, Microsoft, etc.).
  4. WorkOS redirects back to GET /auth/authkit/callback with a code.
  5. The platform exchanges the code, mints a tenant JWT with the user's tenant_id and role, and lands the user on the admin shell.

The local-password path is bypassed entirely when AuthKit is on. Users who only had a password before should expect their old credentials to stop working at cutover.

Inviting a user when SSO is on

Invites work the same way they always have, with one addition: when the invitee accepts, they're added to both the FastYoke tenant and the WorkOS Organization. Removing a member from the FastYoke tenant removes them from the WorkOS Organization too.

The platform never asks you to add a user on the WorkOS side separately. Your only management surface is the FastYoke tenant — the mirror keeps WorkOS in sync.

Failure modes a tenant admin can hit

  • "no active tenant for your WorkOS organization." The WorkOS Organization exists but its FastYoke tenant binding is broken. The most common cause is a tenant that was archived after enablement. Contact platform support; the fix is operator-side, not self-serve.
  • First sign-in from a brand-new domain returns an error. Enablement isn't complete — the operator may have flipped the feature flag without finishing the WorkOS Organization setup. See the operator runbook.
  • An invited user accepts but doesn't see the tenant. The WorkOS mirror lagged. Sign out, sign back in; the mirror finalizes on the next authenticated request.

Operator enablement

Enabling AuthKit for an account is an operator action, not a self-serve toggle. The full enablement sequence — feature flag, sandbox bake, prod flip, rollback — is documented in the internal operator runbook at docs/operations/workos-rollout-runbook.md. The runbook is the authoritative sequence; this customer-facing page deliberately doesn't republish it so the runbook and the docs can't drift out of sync.

REST surface (read-only for tenant admins)

MethodPathPurpose
GET/auth/authkit/signinSign-in entry. Sets the WorkOS state envelope and redirects to WorkOS.
GET/auth/authkit/callbackWorkOS redirect target. Mints a tenant JWT and lands the user on the admin shell.

Both endpoints are driven by the browser sign-in flow; tenant admins don't call them directly.

What's not in WorkOS SSO today

  • SCIM provisioning — push user/group updates from the identity provider directly into the WorkOS Organization.
  • Per-tenant identity-provider configuration from inside the FastYoke admin shell (today the provider is wired in WorkOS).
  • AuthKit disablement self-serve — turning AuthKit off is also an operator action.

See also