feat: add ui for role and role assignment management by adaam2 · Pull Request #1970 · speakeasy-api/gram

adaam2 · 2026-03-24T17:04:16Z

Summary

Role and member role assignment management backed by WorkOS Authorization APIs
UI for managing roles: roles table, create/edit role dialog with permission picker, member assignment with role transition badges
Fine-grained scope/resource grants stored in Gram's principal_grants table
Feature-flagged behind PostHog gram-rbac flag (org-level sidebar nav + route guard)
Moved support/docs/changelog links from header to sidebar "Get help" group

Key Architecture

Hybrid RBAC model: WorkOS owns role definitions + user↔role assignments; Gram's principal_grants table owns fine-grained scope/resource grants
WorkOS EnvironmentRoles (admin, member) are treated as system roles — metadata updates are skipped
WorkOS OrganizationRoles use org- slug prefix, unique per organization
Server resolves between WorkOS role IDs and slugs transparently
No local roles/assignments tables — WorkOS is the sole authority for role CRUD and user↔role mappings

Changes

Server

Goa API design for access service: roles CRUD, member assignment, scopes listing, and principal grants
WorkOS API integration for role and member management
Hardened error handling: 409 conflict on duplicate role creation, system role update safety
Removed low-level grant CRUD endpoints — grants are now managed as part of role create/update
Consolidated access service implementation into single impl.go
Removed auto-provisioning of default grants in favor of a backfill script

Frontend

Roles table with system role badges and actions dropdown
Create/edit role dialog with scope picker using real project/MCP data via useListScopes API
Member assignment with before→after role transition badges
Org-level routing with feature flag guard
Sidebar "Get help" group (support, docs, changelog moved from header)

Database

principal_grants migration for fine-grained scope/resource grants
Removed unused roles and role_assignments tables (WorkOS manages these)

Test plan

Enable gram-rbac feature flag in PostHog
Verify "Roles & Permissions" nav item appears in org sidebar
Create a custom role with permissions and member assignments
Edit an existing role (system roles should have greyed-out name/description)
Change a member's role and verify the before→after badge transition
Delete a custom role
Verify 409 conflict toast when creating a duplicate role name
Verify system roles (admin, member) can be edited without 404 errors
Verify support/docs/changelog links appear in sidebar "Get help" group

🤖 Generated with Claude Code

vercel · 2026-03-24T17:04:17Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
gram-docs-redirect	Ready	Preview, Comment	Mar 25, 2026 1:35pm

changeset-bot · 2026-03-24T17:04:28Z

🦋 Changeset detected

Latest commit: 63f64e2

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
server	Minor
dashboard	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

github-actions · 2026-03-24T17:23:04Z

atlas migrate lint on server/migrations

Status	Step	Result
	No migration files detected
	ERD and visual diff generated	View Visualization
	No issues found	View Report
Read the full linting report on Atlas Cloud

github-actions · 2026-03-24T17:23:16Z

atlas migrate lint on server/clickhouse/migrations

Status	Step	Result
	No migration files detected
	ERD and visual diff generated	View Visualization
	No issues found	View Report
Read the full linting report on Atlas Cloud

An empty resources array (user clicked "Specific projects" but selected none) was treated identically to null (unrestricted), silently inserting a wildcard "*" grant. Now: - Server: nil = wildcard, empty slice = no grant inserted - Frontend: scopes with empty resource lists are filtered out Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Replace http.DefaultClient (no timeout, no retries) with retryablehttp.NewClient().StandardClient() — consistent with the rest of the codebase. This adds automatic retries with backoff for transient failures and a default timeout. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

retryablehttp.NewClient().StandardClient() doesn't set a timeout by default. Add an explicit 30s timeout to prevent indefinite blocking if WorkOS is unresponsive. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Seed script: use Postgres array literal '{id1,id2}' cast to text[] instead of ARRAY[:'org_ids'] which produced a single concatenated string for multi-org seeding - Submit button: count only effective grants (unrestricted or with selected resources) so the button disables when all scopes have empty resource lists Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Replace sequential per-member GetUser API calls with a single paginated ListUsers(organizationID) call. Returns a map for O(1) lookup per membership. Eliminates N round-trips to WorkOS API. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

System roles (admin, member) now have disabled checkboxes and hidden resource pickers in the edit dialog, matching the existing behavior of disabled name/description fields. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

deleteRole onSuccess was only invalidating the roles cache. When a role is deleted, WorkOS reassigns members to a default role, so the members cache must also be invalidated to avoid showing stale role assignments. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

devin-ai-integration

Devin Review found 0 new potential issues.

View 13 additional findings in Devin Review.

Extract RoleProvider interface from concrete *workos.RoleClient so the access service can be tested with an in-memory mock. Add configurable endpoint to RoleClient for httptest-based testing of the actual HTTP layer. Service-layer tests cover CreateRole, UpdateRole, DeleteRole, ListRoles including grant persistence, system role protection, and member counts. RoleClient tests cover all 8 methods against a fake WorkOS HTTP server. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

tgmendes · 2026-03-25T13:40:33Z

server/internal/access/impl.go

+			{Slug: "build:write", Description: "Create and manage projects and deployments", ResourceType: "project"},
+			{Slug: "mcp:read", Description: "View MCP server configurations", ResourceType: "mcp"},
+			{Slug: "mcp:write", Description: "Create and manage MCP server configurations", ResourceType: "mcp"},
+			{Slug: "mcp:connect", Description: "Connect to and use MCP servers", ResourceType: "mcp"},


Note for later: these scopes will be defined in the access package I'm creating in my PR - we should use the constants from there.

devin-ai-integration

Devin Review found 1 new potential issue.

View 13 additional findings in Devin Review.

server/internal/access/impl.go

tgmendes · 2026-03-25T15:28:01Z

server/design/access/design.go

+//     mcp:read, mcp:write, mcp:connect
+//   - Grants are additive (union), no deny
+//   - Each grant is unrestricted (resources=null) or allowlisted (resources=[...])
+// ---------------------------------------------------------------------------


We should probably get rid of these comments - it's the type of comment that'll go stale quite fast

tgmendes · 2026-03-25T15:30:06Z

server/internal/access/impl.go

+		return "", fmt.Errorf("get organization metadata: %w", err)
+	}
+	if !org.WorkosID.Valid || org.WorkosID.String == "" {
+		return "", gen.MakeBadRequest(errors.New("organization is not linked to WorkOS"))


I don't believe this is standard in our codebase - I can't see other places where we use this. You should be using oops here.

This should apply to all gen.Make clauses we have throughout.

disintegrator · 2026-03-25T15:35:11Z

server/design/access/design.go

+
+		Meta("openapi:operationId", "listRoles")
+		Meta("openapi:extension:x-speakeasy-name-override", "listRoles")
+		Meta("openapi:extension:x-speakeasy-react-hook", `{"name": "ListRoles"}`)


Suggested change

Meta("openapi:extension:x-speakeasy-react-hook", `{"name": "ListRoles"}`)

Meta("openapi:extension:x-speakeasy-react-hook", `{"name": "Roles"}`)

disintegrator · 2026-03-25T15:35:28Z

server/design/access/design.go

-		Meta("openapi:extension:x-speakeasy-react-hook", `{"name": "Grants"}`)
+		Meta("openapi:operationId", "getRole")
+		Meta("openapi:extension:x-speakeasy-name-override", "getRole")
+		Meta("openapi:extension:x-speakeasy-react-hook", `{"name": "GetRole"}`)


Suggested change

Meta("openapi:extension:x-speakeasy-react-hook", `{"name": "GetRole"}`)

Meta("openapi:extension:x-speakeasy-react-hook", `{"name": "Role"}`)

disintegrator · 2026-03-25T15:35:37Z

server/design/access/design.go

+
+		Meta("openapi:operationId", "listScopes")
+		Meta("openapi:extension:x-speakeasy-name-override", "listScopes")
+		Meta("openapi:extension:x-speakeasy-react-hook", `{"name": "ListScopes"}`)


Suggested change

Meta("openapi:extension:x-speakeasy-react-hook", `{"name": "ListScopes"}`)

Meta("openapi:extension:x-speakeasy-react-hook", `{"name": "Scopes"}`)

disintegrator · 2026-03-25T15:35:50Z

server/design/access/design.go

-		Meta("openapi:extension:x-speakeasy-react-hook", `{"name": "RemovePrincipalGrants"}`)
+		Meta("openapi:operationId", "listMembers")
+		Meta("openapi:extension:x-speakeasy-name-override", "listMembers")
+		Meta("openapi:extension:x-speakeasy-react-hook", `{"name": "ListMembers"}`)


Suggested change

Meta("openapi:extension:x-speakeasy-react-hook", `{"name": "ListMembers"}`)

Meta("openapi:extension:x-speakeasy-react-hook", `{"name": "Members"}`)

disintegrator · 2026-03-25T15:41:09Z

server/internal/access/impl.go

+	ListRoles(ctx context.Context, orgID string) ([]roles.Role, error)
+	CreateRole(ctx context.Context, orgID string, opts workos.CreateRoleOpts) (*roles.Role, error)
+	UpdateRole(ctx context.Context, orgID string, roleSlug string, opts workos.UpdateRoleOpts) (*roles.Role, error)
+	DeleteRole(ctx context.Context, orgID string, roleSlug string) error
+	ListMembers(ctx context.Context, orgID string) ([]usermanagement.OrganizationMembership, error)
+	UpdateMemberRole(ctx context.Context, membershipID string, roleSlug string) (*usermanagement.OrganizationMembership, error)
+	GetUser(ctx context.Context, userID string) (*usermanagement.User, error)
+	ListOrgUsers(ctx context.Context, orgID string) (map[string]usermanagement.User, error)


the dependence on workos types makes this a leaky abstraction. can we do without it?

tgmendes · 2026-03-25T16:45:53Z

server/internal/thirdparty/workos/roles.go

+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode >= 400 {


Do we want to handle all errors the same way? 4xx and 5xx are different in nature.

Additionally: how will we be handling these upstream (what will the user see)?

tgmendes · 2026-03-25T16:47:01Z

server/internal/thirdparty/workos/roles.go

+	}
+
+	var role roles.Role
+	if err := rc.doAPI(ctx, http.MethodPost, "/authorization/organizations/"+orgID+"/roles", body, &role); err != nil {


Does workos SDK not have this?

tgmendes · 2026-03-25T16:50:59Z

server/internal/thirdparty/workos/roles.go

+
+// doAPI performs a raw HTTP request against the WorkOS REST API.
+// Used for endpoints not covered by the Go SDK (role CRUD).
+func (rc *RoleClient) doAPI(ctx context.Context, method, path string, body []byte, out any) error {


Just for your knowledge, you could just have this method be called do (no need for doAPI). It's a common/well known go idiom.

Not blocking, just information

tgmendes · 2026-03-25T16:56:38Z

server/internal/access/setup_test.go

+// mockRoleProvider is an in-memory implementation of access.RoleProvider for
+// tests. It stores roles and memberships in maps so tests can exercise the
+// service layer without hitting WorkOS.
+type mockRoleProvider struct {


I'm unsure about our DB connections (please check it), but I wouldn't keep the mocks for testing in the same file as the setup_test - I'd expect setup test to be all about setting up the test (and any potential shared test methods). Ignore if this is how we typically do it.

tgmendes · 2026-03-25T17:00:59Z

server/internal/access/impl.go

+	if err != nil {
+		return fmt.Errorf("begin transaction: %w", err)
+	}
+	defer tx.Rollback(ctx) //nolint:errcheck // rollback after commit is a no-op; error is safe to ignore


You should be using:

defer o11y.NoLogDefer(func() error { return dbtx.Rollback(ctx) })

tgmendes · 2026-03-25T17:08:57Z

server/internal/access/impl.go

+		return "", fmt.Errorf("get organization metadata: %w", err)
+	}
+	if !org.WorkosID.Valid || org.WorkosID.String == "" {
+		return "", gen.MakeBadRequest(errors.New("organization is not linked to WorkOS"))


This should apply to all gen.Make clauses we have throughout.

tgmendes · 2026-03-25T17:12:08Z

server/internal/access/impl.go

+		Description: p.Description,
+	})
+	if err != nil {
+		if strings.Contains(err.Error(), "409") || strings.Contains(err.Error(), "slug_conflict") || strings.Contains(err.Error(), "already in use") {


Is this the only way to check for WorkOS errors? I'd like to avoid these string comparisons if possible - they're a recipe for disaster. Tomorrow WorkOS changes the wording and our logic blows up (this happened with Polar recently)

tgmendes · 2026-03-25T17:13:54Z

server/internal/access/impl.go

-	return &gen.UpsertGrantsResult{Grants: grants}, nil
+	// Sync scope grants to local DB. If this fails, clean up the WorkOS role
+	// to avoid leaving an orphan.
+	if len(p.Grants) > 0 {


Suggestion: move this line to the syncGrants method. It will save you a nested if.

Inside syncGrants your first line can be:

if len(grants) == 0 { return nil }

## Summary - Adds `RoleClient` to the WorkOS third-party package wrapping WorkOS role and membership APIs - Supports listing, creating, updating, and deleting org-scoped roles via raw HTTP - Supports listing org members, updating member role assignments, and fetching user details via WorkOS SDK - Uses a retryable HTTP client (30s timeout) for resilience - Exposes `NewRoleClientWithEndpoint` for hermetic testing against an `httptest.Server` Part of the RBAC feature split from #1970.  --- <a href="https://app.devin.ai/review/speakeasy-api/gram/pull/2011" target="_blank"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://static.devin.ai/assets/gh-open-in-devin-review-dark.svg?v=1"> <img src="https://static.devin.ai/assets/gh-open-in-devin-review-light.svg?v=1" alt="Open with Devin"> </picture> </a>

vercel bot deployed to Preview March 24, 2026 17:04 View deployment

adaam2 requested a review from a team as a code owner March 24, 2026 17:04

This comment was marked as resolved.

Sign in to view

vercel bot deployed to Preview March 24, 2026 17:12 View deployment

This comment was marked as resolved.

Sign in to view

adaam2 force-pushed the feat/rbac branch from ce43e33 to 655ece2 Compare March 24, 2026 17:21

vercel bot deployed to Preview March 24, 2026 17:22 View deployment

adaam2 changed the title ~~feat: RBAC roles & permissions with WorkOS integration~~ feat: add RBAC roles and permissions with WorkOS integration Mar 24, 2026

This comment has been minimized.

Sign in to view

This comment was marked as resolved.

Sign in to view

vercel bot deployed to Preview March 24, 2026 17:37 View deployment

vercel bot deployed to Preview March 24, 2026 17:43 View deployment

This comment was marked as resolved.

Sign in to view

vercel bot deployed to Preview March 25, 2026 09:38 View deployment

adaam2 changed the title ~~feat: add RBAC roles and permissions with WorkOS integration~~ feat: RBAC roles and permissions via WorkOS Mar 25, 2026

adaam2 force-pushed the feat/rbac branch from 76f9727 to 4d87798 Compare March 25, 2026 09:42

vercel bot deployed to Preview March 25, 2026 09:43 View deployment

vercel bot deployed to Preview March 25, 2026 09:47 View deployment

vercel bot deployed to Preview March 25, 2026 09:49 View deployment

vercel bot deployed to Preview March 25, 2026 09:50 View deployment

This comment has been minimized.

Sign in to view

This comment was marked as resolved.

Sign in to view

vercel bot deployed to Preview March 25, 2026 10:00 View deployment

vercel bot deployed to Preview March 25, 2026 10:07 View deployment

adaam2 changed the title ~~feat: RBAC roles and permissions via WorkOS~~ feat: add ui for role and role assignment management Mar 25, 2026

vercel bot deployed to Preview March 25, 2026 12:39 View deployment

vercel bot deployed to Preview March 25, 2026 12:44 View deployment

fix: add 30s timeout to WorkOS retryable HTTP client

316f29a

retryablehttp.NewClient().StandardClient() doesn't set a timeout by default. Add an explicit 30s timeout to prevent indefinite blocking if WorkOS is unresponsive. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

vercel bot deployed to Preview March 25, 2026 12:45 View deployment

This comment was marked as resolved.

Sign in to view

vercel bot deployed to Preview March 25, 2026 12:58 View deployment

vercel bot deployed to Preview March 25, 2026 13:01 View deployment

fix: populate all ListUsersOpts fields to satisfy exhaustruct lint

aa28b22

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

This comment was marked as resolved.

Sign in to view

vercel bot deployed to Preview March 25, 2026 13:08 View deployment

vercel bot deployed to Preview March 25, 2026 13:10 View deployment

This comment was marked as resolved.

Sign in to view

vercel bot deployed to Preview March 25, 2026 13:20 View deployment

devin-ai-integration bot reviewed Mar 25, 2026

View reviewed changes

vercel bot deployed to Preview March 25, 2026 13:35 View deployment

tgmendes reviewed Mar 25, 2026

View reviewed changes

devin-ai-integration bot reviewed Mar 25, 2026

View reviewed changes

server/internal/access/impl.go Show resolved Hide resolved

adaam2 requested a review from qstearns March 25, 2026 13:45

tgmendes reviewed Mar 25, 2026

View reviewed changes

disintegrator reviewed Mar 25, 2026

View reviewed changes

tgmendes reviewed Mar 25, 2026

View reviewed changes

tgmendes mentioned this pull request Mar 27, 2026

feat: add WorkOS RoleClient for role and membership management #2011

Merged

	Meta("openapi:extension:x-speakeasy-react-hook", `{"name": "ListRoles"}`)
	Meta("openapi:extension:x-speakeasy-react-hook", `{"name": "Roles"}`)

Conversation

adaam2 commented Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Key Architecture

Changes

Server

Frontend

Database

Test plan

Uh oh!

vercel bot commented Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

github-actions bot commented Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Mar 24, 2026

Uh oh!

This comment has been minimized.

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment has been minimized.

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

devin-ai-integration bot left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

disintegrator Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adaam2 commented Mar 24, 2026 •

edited

Loading

vercel bot commented Mar 24, 2026 •

edited

Loading

changeset-bot bot commented Mar 24, 2026 •

edited

Loading

github-actions bot commented Mar 24, 2026 •

edited

Loading

disintegrator Mar 25, 2026 •

edited

Loading