feat: Add RBAC organization roles API support

[csrbarber]

Summary

• Add organization role endpoints to RBAC module: createOrganizationRole, listOrganizationRoles, getOrganizationRole, updateOrganizationRole, setOrganizationRolePermissions, addOrganizationRolePermission, removeOrganizationRolePermission
• All endpoints return Role — no separate resource class needed since the API returns "object": "role" for all role types
• Does not modify existing Organizations::listOrganizationRoles

Part 3 of 3 for RBAC support. Stacked on #338.

Test plan

• 7 new tests covering each organization role endpoint
• All existing tests pass

🤖 Generated with Claude Code

[linear]

ENT-4805 workos-php

[greptile-apps]

Greptile Summary

This PR completes Part 3 of RBAC support by adding 7 organization role endpoints to the RBAC class and introducing an OrganizationRole resource. The implementation closely mirrors the existing environment role pattern stacked in the prior PRs.

Key changes:

• New Resource\OrganizationRole class with the same attribute set as Resource\Role — distinguished semantically so mutation responses return OrganizationRole while read/list responses return Role.
• Seven new methods on RBAC: createOrganizationRole, listOrganizationRoles, getOrganizationRole, updateOrganizationRole, setOrganizationRolePermissions, addOrganizationRolePermission, removeOrganizationRolePermission.
• 7 new unit tests, one per method. Tests use correct mock fixtures and exercise the happy path for each endpoint.

Notable observations:

• listOrganizationRoles returns [$roles] — a single-element array wrapping the roles array — consistent with listEnvironmentRoles but differing from listPermissions. This requires callers to destructure unnecessarily, and a plain return $roles would be cleaner for a non-paginated list.
• updateOrganizationRole sends an empty PATCH body if called with no optional arguments, silently resulting in a no-op. The same pattern exists in updateEnvironmentRole and updatePermission, so this is not a regression.
• testGetOrganizationRole asserts the response against organizationRoleFixture() even though getOrganizationRole returns a Resource\Role instance. The test passes only because both classes share identical attribute mappings — the return type is not actually verified by the assertion.

Confidence Score: 4/5

• This PR is safe to merge with minor style improvements recommended before shipping.
• The implementation is logically correct, consistently follows existing patterns, and is covered by unit tests for all new endpoints. No critical logic errors or security issues were found. The score is reduced slightly due to the non-intuitive [$roles] return shape in listOrganizationRoles and the missing return-type assertion in testGetOrganizationRole, both of which could create maintenance confusion downstream.
• lib/RBAC.php — specifically the listOrganizationRoles return shape and updateOrganizationRole empty-params behaviour.

Important Files Changed

Filename	Overview
lib/RBAC.php	Adds 7 new organization role methods following existing environment role patterns. Minor concerns: listOrganizationRoles wraps results in an extra array level, and updateOrganizationRole silently no-ops when called without any update fields.
lib/Resource/OrganizationRole.php	New resource class mirroring Role exactly — same RESOURCE_ATTRIBUTES and RESPONSE_TO_RESOURCE_KEY. The distinction from Role is purely semantic (mutation return type). Clean and correctly structured.
tests/WorkOS/RBACTest.php	7 new tests covering each added endpoint. testGetOrganizationRole uses organizationRoleFixture() against a Role return type — the assertion passes only because both classes share identical attributes, not because the return type is verified.

Sequence Diagram

sequenceDiagram
    participant Caller
    participant RBAC
    participant Client
    participant API

    Caller->>RBAC: createOrganizationRole(orgId, slug, name, desc?)
    RBAC->>Client: POST authorization/organizations/{orgId}/roles
    Client->>API: HTTP POST
    API-->>Client: OrganizationRole JSON
    Client-->>RBAC: decoded array
    RBAC-->>Caller: Resource\OrganizationRole

    Caller->>RBAC: listOrganizationRoles(orgId)
    RBAC->>Client: GET authorization/organizations/{orgId}/roles
    Client->>API: HTTP GET
    API-->>Client: list JSON {data: [...]}
    Client-->>RBAC: decoded array
    RBAC-->>Caller: [Resource\Role[]]

    Caller->>RBAC: getOrganizationRole(orgId, slug)
    RBAC->>Client: GET authorization/organizations/{orgId}/roles/{slug}
    Client->>API: HTTP GET
    API-->>Client: Role JSON
    Client-->>RBAC: decoded array
    RBAC-->>Caller: Resource\Role

    Caller->>RBAC: updateOrganizationRole(orgId, slug, name?, desc?)
    RBAC->>Client: PATCH authorization/organizations/{orgId}/roles/{slug}
    Client->>API: HTTP PATCH
    API-->>Client: OrganizationRole JSON
    Client-->>RBAC: decoded array
    RBAC-->>Caller: Resource\OrganizationRole

    Caller->>RBAC: setOrganizationRolePermissions(orgId, slug, perms[])
    RBAC->>Client: PUT authorization/organizations/{orgId}/roles/{slug}/permissions
    Client->>API: HTTP PUT
    API-->>Client: OrganizationRole JSON
    Client-->>RBAC: decoded array
    RBAC-->>Caller: Resource\OrganizationRole

    Caller->>RBAC: addOrganizationRolePermission(orgId, roleSlug, permSlug)
    RBAC->>Client: POST authorization/organizations/{orgId}/roles/{roleSlug}/permissions
    Client->>API: HTTP POST
    API-->>Client: OrganizationRole JSON
    Client-->>RBAC: decoded array
    RBAC-->>Caller: Resource\OrganizationRole

    Caller->>RBAC: removeOrganizationRolePermission(orgId, roleSlug, permSlug)
    RBAC->>Client: DELETE authorization/organizations/{orgId}/roles/{roleSlug}/permissions/{permSlug}
    Client->>API: HTTP DELETE
    API-->>Client: empty response
    Client-->>RBAC: []
    RBAC-->>Caller: []

Loading

_{Last reviewed commit: 78ed5d7}