Add authorization environment roles support

[csrbarber]

Description

Add CRUD operations for environment roles including create, list, get, update, set/add permissions on the authorization module.

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.

[linear]

ENT-4799 workos-python

[greptile-apps]

Greptile Overview

Greptile Summary

Added comprehensive CRUD operations for environment roles in the authorization module, including create, list, get, update, and permission management endpoints. Introduced a Role union type that discriminates between EnvironmentRole and OrganizationRole, allowing the organization role endpoints to return either type through Pydantic's discriminated union feature.

Key Changes:

• Implemented 6 new environment role methods with both sync and async variants
• Created EnvironmentRole model mirroring OrganizationRole structure but without organization_id field
• Added Role union type with type field discriminator for polymorphic role handling
• Updated organization role list/get methods to return RoleList/Role union types instead of concrete types
• Added comprehensive test coverage with 6 new test cases using consistent mocking patterns

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• The implementation follows established patterns in the codebase, includes both sync and async variants, has comprehensive test coverage, uses proper Pydantic discriminated unions for type safety, and mirrors the existing organization role structure
• No files require special attention

Important Files Changed

Filename	Overview
workos/types/authorization/role.py	Introduced Role union type with discriminator for EnvironmentRole and OrganizationRole, and RoleList for listing both role types
workos/types/authorization/environment_role.py	Added EnvironmentRole model with proper fields and type discriminator, mirroring OrganizationRole structure
workos/authorization.py	Implemented complete CRUD operations for environment roles (create, list, get, update, set/add permissions) with both sync and async support
tests/test_authorization.py	Added comprehensive test coverage for all environment role operations with proper assertions and mocking

Sequence Diagram

sequenceDiagram
    participant Client
    participant Authorization
    participant HTTPClient
    participant API as WorkOS API

    Note over Client,API: Create Environment Role
    Client->>Authorization: create_environment_role(slug, name, description)
    Authorization->>HTTPClient: POST /authorization/roles
    HTTPClient->>API: Request with {slug, name, description}
    API-->>HTTPClient: 201 Created (EnvironmentRole JSON)
    HTTPClient-->>Authorization: Response
    Authorization-->>Client: EnvironmentRole object

    Note over Client,API: List Environment Roles
    Client->>Authorization: list_environment_roles()
    Authorization->>HTTPClient: GET /authorization/roles
    HTTPClient->>API: Request
    API-->>HTTPClient: 200 OK (EnvironmentRoleList JSON)
    HTTPClient-->>Authorization: Response
    Authorization-->>Client: EnvironmentRoleList object

    Note over Client,API: Get Environment Role
    Client->>Authorization: get_environment_role(slug)
    Authorization->>HTTPClient: GET /authorization/roles/{slug}
    HTTPClient->>API: Request
    API-->>HTTPClient: 200 OK (EnvironmentRole JSON)
    HTTPClient-->>Authorization: Response
    Authorization-->>Client: EnvironmentRole object

    Note over Client,API: Update Environment Role
    Client->>Authorization: update_environment_role(slug, name, description)
    Authorization->>HTTPClient: PATCH /authorization/roles/{slug}
    HTTPClient->>API: Request with {name, description}
    API-->>HTTPClient: 200 OK (EnvironmentRole JSON)
    HTTPClient-->>Authorization: Response
    Authorization-->>Client: EnvironmentRole object

    Note over Client,API: Set Role Permissions
    Client->>Authorization: set_environment_role_permissions(slug, permissions)
    Authorization->>HTTPClient: PUT /authorization/roles/{slug}/permissions
    HTTPClient->>API: Request with {permissions}
    API-->>HTTPClient: 200 OK (EnvironmentRole JSON)
    HTTPClient-->>Authorization: Response
    Authorization-->>Client: EnvironmentRole object

    Note over Client,API: Add Role Permission
    Client->>Authorization: add_environment_role_permission(slug, permission_slug)
    Authorization->>HTTPClient: POST /authorization/roles/{slug}/permissions
    HTTPClient->>API: Request with {slug: permission_slug}
    API-->>HTTPClient: 200 OK (EnvironmentRole JSON)
    HTTPClient-->>Authorization: Response
    Authorization-->>Client: EnvironmentRole object

Loading

_{Last reviewed commit: d7496b7}

[greptile-apps]

_{6 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}