fix(auth): scope AuthKit sessions to an organization

[gjtorikian]

Summary

• Fresh logins now resolve an organization. Every grant except mfa-totp, organization-selection, and a refresh carrying an explicit organization_id could only mint an unscoped session. Tokens therefore never carried org_id, role, or permissions, so any API authorizing on the org claim rejected every token the emulator issued. A single active membership is now selected implicitly; several return organization_selection_required (403) as production does; none leaves organization_id null rather than inventing one.
• The organization-selection grant is reachable and validated. organization_selection_required was never emitted, so the grant was unreachable except after an MFA challenge; it also never checked that the user was an active member of the organization it was handed. It does now, reporting organization_membership_not_found (the spec's code for that case, previously mis-reported as invalid_organization_id), and it checks before consuming the pending token so a wrong pick can be retried.
• invitation_token is honored on authorization_code, password, and Magic Auth. It is the only way a caller can name an organization on a grant that takes no organization_id. The emulator ignored the field entirely, so an invited user landed in an unscoped session, the invitation stayed pending forever, and a multi-organization user hit a selection prompt they should never have seen. The token is validated before the grant runs so a bad invitation can't burn the one-time code in the same request, and it's carried across an MFA challenge rather than accepted early, so nothing is consumed until the second factor proves who is signing in.
• Invitation acceptance is shared with the invitations REST route, which previously duplicated a membership when one already existed and could not readmit a deactivated member.
• Access tokens now carry roles alongside role. Production emits both and the WorkOS SDKs read the plural; a token with only role passed locally and lost the claim in production.

Breaking change

Multi-organization users now receive a 403 organization_selection_required where they previously received a 200 with a null organization. This matches production, but any test fixture relying on the old unscoped response will need to complete the selection step.

[greptile-apps]

Greptile Summary

The PR scopes fresh AuthKit sessions to organizations and completes the invitation-continuation fixes.

• Resolves a single active organization automatically and requires explicit selection when several are available.
• Validates organization membership before issuing organization-scoped sessions.
• Defers invitation acceptance across MFA and organization-selection continuations until authentication can complete.
• Reuses or reactivates memberships when invitations are accepted.
• Adds the plural roles access-token claim and documents the new behavior.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains; current code revalidates deferred invitations before consuming continuation state and postpones invitation acceptance until organization selection has completed.

Important Files Changed

Filename	Overview
src/workos/routes/auth.ts	Adds organization resolution, membership validation, continuation-safe invitation handling, and organization-scoped token issuance; the previously reported continuation-state defects are fixed.
src/workos/helpers.ts	Centralizes invitation acceptance while reusing existing memberships and reactivating inactive ones.
src/workos/routes/invitations.ts	Replaces duplicated invitation-acceptance logic with the shared helper.
src/core/jwt.ts	Extends access-token payloads with the plural roles claim.
src/workos/routes/auth.spec.ts	Adds coverage for organization resolution, selection, invitation deferral, MFA continuation, membership reactivation, and token claims.
README.md	Documents organization-scoped sessions, invitation behavior, organization selection, and refresh-token rotation.

Sequence Diagram

sequenceDiagram
    participant Client
    participant Auth as Authenticate route
    participant Pending as Pending auth store
    participant Invite as Invitation store
    Client->>Auth: Fresh login with invitation_token
    Auth->>Invite: Validate pending invitation
    alt MFA required
        Auth->>Pending: Store user, method, org, invitation token
        Auth-->>Client: mfa_challenge
        Client->>Auth: MFA code + pending token
        Auth->>Invite: Revalidate invitation
    end
    alt Multiple active organizations and no selected org
        Auth->>Pending: Store continuation including invitation token
        Auth-->>Client: organization_selection_required
        Client->>Auth: Selected organization + pending token
        Auth->>Auth: Validate active membership
        Auth->>Invite: Revalidate invitation
    end
    Auth->>Invite: Accept invitation
    Auth-->>Client: Organization-scoped session and tokens

Loading

_{Reviews (2): Last reviewed commit: "fix(auth): spend an invitation only once..." | Re-trigger Greptile}