fix: add invitation_token parameter to authentication methods

[gjtorikian]

Description

Based on the WorkOS API documentation, this kwarg is missing.

Closes #337

Documentation

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

[ ] Yes

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

[greptile-apps]

Greptile Overview

Greptile Summary

This PR adds an optional invitation_token keyword argument to three User Management authentication entrypoints (authenticate_with_password, authenticate_with_code, authenticate_with_magic_auth) and forwards it to the /user_management/authenticate request body. Specs were added to assert the new parameter is included in the request payload when provided.

Key integration point is WorkOS::UserManagement building request bodies that are serialized by WorkOS::Client.post_request (JSON via body.to_json).

Confidence Score: 3/5

• This PR is close to mergeable but has a couple of correctness issues in request body construction and the new specs.
• The core API surface change is small, but the new parameter is currently serialized as JSON null when omitted (unlike other optional params in this client), and the new specs stub post_request with an argument shape that doesn’t match the method signature, so they may not actually assert what they intend.
• lib/workos/user_management.rb; spec/lib/workos/user_management_spec.rb

Important Files Changed

Filename	Overview
lib/workos/user_management.rb	Adds optional invitation_token kwarg to password, code, and magic auth authentication methods and passes it through to the authenticate request body.
spec/lib/workos/user_management_spec.rb	Adds specs asserting invitation_token is included in request body for three authentication methods; uses request stubbing rather than VCR.

Sequence Diagram

sequenceDiagram
  participant App as App (workos-ruby)
  participant UM as WorkOS::UserManagement
  participant Client as WorkOS::Client
  participant API as WorkOS API

  App->>UM: authenticate_with_password(..., invitation_token)
  UM->>Client: post_request(path:"/user_management/authenticate", body:{..., invitation_token})
  Client->>API: HTTPS POST /user_management/authenticate (JSON)
  API-->>Client: 2xx response (tokens + user)
  Client-->>UM: response
  UM-->>App: AuthenticationResponse

  App->>UM: authenticate_with_code(..., invitation_token)
  UM->>Client: post_request(... body includes invitation_token)
  Client->>API: HTTPS POST /user_management/authenticate
  API-->>Client: 2xx response
  Client-->>UM: response
  UM-->>App: AuthenticationResponse

  App->>UM: authenticate_with_magic_auth(..., invitation_token)
  UM->>Client: post_request(... body includes invitation_token)
  Client->>API: HTTPS POST /user_management/authenticate
  API-->>Client: 2xx response
  Client-->>UM: response
  UM-->>App: AuthenticationResponse

Loading

[greptile-apps]

_{2 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Additional Comments (1)

lib/workos/user_management.rb
Nil field serialized as null

These methods always include invitation_token in the request body, even when it’s nil (see lib/workos/user_management.rb:327). Since post_request does body.to_json, that key will be sent as JSON null, which differs from other request bodies in this file that use .compact to omit optional fields and can break API validation if the parameter must be omitted when unused. Consider compacting the body (or conditionally adding the key) for authenticate_with_password, authenticate_with_code, and authenticate_with_magic_auth.