@hetuh/ext-orgws

A Better Auth plugin that extends the built-in organization plugin with a workspace layer, dynamic role-based access control, and an optional membership-sync cache for apps that delegate identity to an upstream auth server.

Drop-in replacement for better-auth/plugins/organization — it keeps the full organization/team/member/invitation API and adds workspaces and dynamic RBAC on top.

Install

npm install @hetuh/ext-orgws
# peer dependency (1.7+ — the plugin uses 1.7's atomic adapter operations):
npm install better-auth

What it adds

• Workspaces — a sub-organization grouping (workspace, workspaceMember, teamWorkspaceAccess) with their own CRUD, membership, and invitation endpoints.
• Dynamic access control — roles/permissions stored in a dynamicRole table, editable at runtime, on top of Better Auth's static ac statements.
• Membership sync — optional upsert-based caching of organizations, teams, and members fetched from an upstream auth server (on login, on stale TTL, or on demand), so a downstream app can mirror identity without owning it.

Usage

Server

import { betterAuth } from 'better-auth'
import { organization } from '@hetuh/ext-orgws'

export const auth = betterAuth({
  // ...
  plugins: [
    organization({
      teams: { enabled: true },
      workspaces: { enabled: true },
      dynamicAccessControl: { enabled: true },
      // optional: mirror memberships from an upstream auth server
      sync: {
        fetchMemberships: async (userId) => fetchFromUpstream(userId),
        syncOnLogin: true,
        staleTtlMs: 4 * 60 * 60 * 1000,
      },
    }),
  ],
})

Client

import { createAuthClient } from 'better-auth/client'
import { organizationClient } from '@hetuh/ext-orgws/client'

export const authClient = createAuthClient({
  plugins: [organizationClient()],
})

Relationship to Better Auth

This package extends and is derived in part from Better Auth's organization plugin. Treat its organization/team/member/invitation surface as compatible with Better Auth's; the workspace and dynamic-RBAC surface is the addition.

Tracks Better Auth 1.7: race-free team capacity via atomic seat reservation (team.memberCount counter + unique teamMember.membershipKey), the lightweight GET /organization/get-organization endpoint, and list-user-teams with userId/organizationId query parameters. See CHANGELOG.md for the schema migration notes.

License

MIT — see LICENSE. Includes portions derived from Better Auth (MIT).