add authenticate with invite_token to authenticate_with_code

[simzeee]

Description

Addressing this linear ticket here

https://linear.app/workos/issue/FEAT-1315/support-invitation-token-in-authenticate-call-in-the-python-sdk

Adding capability to authenticate_with_code using the invitation_token

Documentation

Does this require changes to the WorkOS Docs?

[ X] Yes, this will require a change to the docs here 

API reference https://workos.com/docs/reference/authkit/authentication/code
(screenshots in linear ticket)

I can add this to the docs too and create the PR, but I want to make sure this PR is approved first

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 adds support for the `invitation_token` parameter to the `authenticate_with_code` method in the WorkOS Python SDK. The change enables users to authenticate with an OAuth authorization code while simultaneously providing an invitation token, supporting invitation-based authentication flows where users can accept organization invitations during the authentication process.

The implementation spans three main areas:

1. Type definitions - Added invitation_token as an optional Union[str, None] field to AuthenticateWithCodeParameters in the common authentication types
2. Core functionality - Updated both sync and async versions of authenticate_with_code in the UserManagement class to accept and include the invitation token in API requests
3. Test coverage - Added comprehensive test validation to ensure the invitation token is properly passed through the authentication flow

This change integrates seamlessly with the existing authentication system, maintaining backward compatibility since the parameter is optional. The implementation follows established patterns in the codebase, particularly mirroring how invitation tokens are already supported in the create_magic_auth method. This enhancement addresses Linear ticket FEAT-1315 and aligns with WorkOS's broader invitation system architecture.

Important Files Changed

Changed Files

Filename	Score	Overview
workos/user_management.py	5/5	Added invitation_token parameter to authenticate_with_code method in both sync and async implementations
workos/types/user_management/authenticate_with_common.py	5/5	Added invitation_token field to AuthenticateWithCodeParameters TypedDict as optional parameter
tests/test_user_management.py	5/5	Added comprehensive test case to verify invitation token functionality in authentication flow

Confidence score: 5/5

• This PR is safe to merge with minimal risk as it adds optional functionality without breaking existing flows
• Score reflects straightforward implementation following established patterns with comprehensive test coverage
• No files require special attention as all changes are well-implemented and follow existing conventions

Sequence Diagram

sequenceDiagram
    participant User
    participant TestUserManagement as Test Suite
    participant UserManagement as UserManagement Module
    participant HTTPClient as HTTP Client
    participant WorkOSAPI as WorkOS API

    Note over User, WorkOSAPI: Test: authenticate_with_code with invitation_token

    User->>TestUserManagement: "Run test_authenticate_with_code_with_invitation_token"
    TestUserManagement->>TestUserManagement: "Setup test parameters with invitation_token"
    TestUserManagement->>UserManagement: "authenticate_with_code(code, invitation_token, ...)"
    UserManagement->>UserManagement: "Build AuthenticateWithCodeParameters payload"
    UserManagement->>UserManagement: "Add client_id and client_secret to payload"
    UserManagement->>HTTPClient: "request(USER_AUTHENTICATE_PATH, POST, json=payload)"
    HTTPClient->>WorkOSAPI: "POST /user_management/authenticate"
    WorkOSAPI-->>HTTPClient: "Authentication response with user data"
    HTTPClient-->>UserManagement: "Return response data"
    UserManagement->>UserManagement: "Validate response with AuthKitAuthenticationResponse"
    UserManagement-->>TestUserManagement: "Return AuthenticationResponse object"
    TestUserManagement->>TestUserManagement: "Assert response contains expected user data"
    TestUserManagement->>TestUserManagement: "Assert payload includes invitation_token"
    TestUserManagement-->>User: "Test passes - invitation_token properly included"

Loading

_{3 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}