AuthKit multiple roles support

[csrbarber]

Description

• Add roles to organization membership resource responses (get, list, create, update, deactivate, reactivate)
• Add role_slugs parameter to organization membership create and update
• Add roles support to session JWT decoding

Testing

• Tested OM CREATE and UPDATE with role_slugs
• Tested roles coming through on auth using ruby-authkit-example pointing at my local SDK

Documentation

Does this require changes to the WorkOS Docs? E.g. the API Reference or code snippets need updates.

[X] Yes

If yes, link a related docs PR and add a docs maintainer as a reviewer. Their approval is required.

[greptile-apps]

Greptile Overview

Summary

This PR implements AuthKit multiple roles support, extending WorkOS's role-based access control from single roles to multiple roles per organization membership. The changes introduce a new `roles` array field alongside the existing single `role` field to maintain backward compatibility during the transition period.

The implementation spans three main areas:

1. Organization Membership Enhancement: The OrganizationMembership class now includes a roles attribute that initializes as an empty array if not present in the API response. This works alongside the existing role field, allowing the API to return both formats during migration.

2. User Management API Updates: The create_organization_membership and update_organization_membership methods now accept a role_slugs parameter (array) in addition to the existing role_slug parameter (string). The implementation uses conditional assignment to build request bodies dynamically, ensuring only non-nil parameters are sent.

3. Session JWT Support: The Session class now extracts a roles claim from JWT tokens, defaulting to an empty array when the claim isn't present. This ensures session authentication responses include both legacy and new role information.

The changes maintain full backward compatibility by preserving existing single-role functionality while adding multi-role capabilities. The API responses now include both role (showing the primary/first role) and roles (showing all assigned roles) fields. Comprehensive test coverage has been added with VCR cassettes capturing the new API interactions, and the implementation follows established patterns in the codebase for handling optional fields with fallback values.

Important Files Changed

Changed Files

Filename	Score	Overview
lib/workos/organization_membership.rb	5/5	Adds roles array attribute with proper initialization and JSON serialization
lib/workos/user_management.rb	4/5	Implements role_slugs parameter support for create/update operations with backward compatibility
lib/workos/session.rb	5/5	Adds roles extraction from JWT tokens with empty array fallback
spec/lib/workos/user_management_spec.rb	4/5	Comprehensive test coverage for multiple roles functionality using VCR cassettes
spec/lib/workos/session_spec.rb	5/5	Updates session tests to include roles array in JWT payloads and responses
spec/support/fixtures/vcr_cassettes/user_management/create_organization_membership/valid_multiple_roles.yml	5/5	Test fixture capturing API interaction for creating memberships with multiple roles
spec/support/fixtures/vcr_cassettes/user_management/update_organization_membership/valid_multiple_roles.yml	5/5	Test fixture capturing API interaction for updating memberships with multiple roles
.gitignore	5/5	Standard addition of IntelliJ IDEA configuration directory

Confidence score: 4/5

• This PR is safe to merge with minimal risk as it maintains backward compatibility through dual-field support
• Score reflects well-structured implementation following existing patterns, though the dual-parameter approach in user management methods adds some complexity
• Pay close attention to the user management methods to ensure the conditional parameter logic works correctly in all scenarios

Sequence Diagram

sequenceDiagram
    participant User
    participant App as Ruby Application
    participant WorkOS as WorkOS API
    participant JWT as JWT Token

    User->>App: "Create organization membership with multiple roles"
    App->>WorkOS: "POST /user_management/organization_memberships"
    Note over App,WorkOS: body: { user_id, organization_id, role_slugs: ["admin", "member"] }
    WorkOS-->>App: "OrganizationMembership with roles array"
    App-->>User: "Membership created with multiple roles"

    User->>App: "Update organization membership roles"
    App->>WorkOS: "PUT /user_management/organization_memberships/{id}"
    Note over App,WorkOS: body: { role_slugs: ["admin", "editor"] }
    WorkOS-->>App: "Updated OrganizationMembership with new roles"
    App-->>User: "Roles updated successfully"

    User->>App: "Authenticate user session"
    App->>WorkOS: "Authenticate request"
    WorkOS-->>App: "JWT access token with roles claim"
    App->>JWT: "Decode JWT token"
    JWT-->>App: "Decoded claims including roles array"
    Note over App: roles: ["admin", "editor"]
    App-->>User: "Authentication response with roles"

Loading

_{8 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}