Organization Settings & Members
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Organization Settings & Members module is a critical component of the Barekey vault manager, responsible for managing the administrative lifecycle and access control of teams. Barekey utilizes Clerk for authentication and organization management, while Convex serves as the backend BaaS (Backend-as-a-Service) for hosting logic and data. Within this system, organizations (often referred to as workspaces) act as the primary owners of projects and secrets, as individual users cannot own projects directly.
Sources: AGENTS.md:5-40, pkg/ui/src/pages/o/[org]/settings/page.tsx:102-110
The scope of this module includes workspace profile management (naming, slugification, and logos), member directory management (invitations, role assignments, and removals), and billing tier configuration. Access is strictly controlled via roles, ensuring that sensitive administrative actions like member removal or project deletion are restricted to authorized personnel.
Sources: pkg/ui/src/pages/o/[org]/settings/page.tsx:320-450, pkg/ui/src/pages/o/[org]/members/page.tsx:110-150
Architecture and Integration
Barekey integrates Clerk and Convex to provide a seamless organization management experience. Clerk handles the identity and membership state, while the Barekey UI consumes this state through specialized hooks like useOrganization and useOrganizationList.
Authentication and Authorization Flow
When a user accesses an organization-scoped route (/o/[org]), the system verifies the user's membership and active organization status. If the current route's slug does not match the active organization ID in the Clerk session, a switching process is triggered to align the workspace context.
Key Components
The organization workspace utilizes several specialized UI components for a consistent developer experience (DX).
| Component | Description |
|---|---|
OrgPageHero | Standardized header displaying the title, subtitle, and organization metadata tags. |
OrgSectionCard | A container for administrative sections with optional action buttons. |
OrgRoleBadge | Visual indicator for the user's role (Admin vs Member). |
OrgMetricCard | Displays quantitative data like member counts or pending invites. |
Sources: pkg/ui/src/components/custom/org-workspace.tsx:50-150
Workspace Profile Management
Organization settings allow administrators to modify the workspace's public identity. This includes the display name, unique URL slug, and logo.
Slug Policy and Generation
Barekey enforces a strict slug policy for organizations and projects. Slugs must match ^[a-z0-9]+$ (lowercase letters and digits only). When updating an organization name, the system attempts to generate a unique slug candidate using a retry loop (up to 8 attempts) to handle identifier collisions in Clerk.
Member Management and Access Control
The membership system supports three primary states: active members, pending invitations, and membership requests.
Member Directory
The directory provides a searchable and sortable list of all current workspace members. Sorting modes include alphabetical, role-grouped (Admins first), and chronological (newest/oldest added).
| Sort Mode | Description |
|---|---|
alphabetical_asc | Standard A-Z sorting by name. |
role_grouped | Prioritizes org:admin over org:member. |
newest_added | Sorts by createdAt timestamp descending. |
email_asc | Sorts by the primary identifier (email). |
Sources: pkg/ui/src/pages/o/[org]/members/page.tsx:28-50, pkg/ui/src/pages/o/[org]/members/page.tsx:75-105
Administrative Actions
Admins can remove members through the settings interface. The system includes a "Danger Zone" allowing users to leave a workspace, which permanently removes their access until they are re-invited.
Sources: pkg/ui/src/pages/o/[org]/settings/page.tsx:210-240, pkg/ui/src/pages/o/[org]/settings/page.tsx:440-460
Organization Billing
Barekey implements three billing tiers: Free, Pro, and Max. Each tier defines limits for static requests, dynamic requests, and storage.
| Tier | Price (Monthly) | Key Features |
|---|---|---|
| Free | $0 | 10k Static, 500 Dynamic, 25MB Storage |
| Pro | $9 | 250k Static, 5k Dynamic, 250MB Storage |
| Max | $39 | 2M Static, 25k Dynamic, 2GB Storage |
Sources: pkg/ui/src/pages/o/[org]/billing/page.tsx:15-80
The billing UI allows users to toggle between monthly and annual billing (the latter providing a 20% discount) and to preview costs with or without overage charges. Overage usage for Pro and Max plans is billed monthly regardless of the base billing interval.
Sources: pkg/ui/src/pages/o/[org]/billing/page.tsx:105-130, pkg/ui/src/pages/o/[org]/billing/page.tsx:225-235
Conclusion
The Organization Settings & Members module provides the foundational infrastructure for team-based secret management in Barekey. By leveraging Clerk for identity and membership state, and Convex for backend operations, it ensures that workspace administration—from initial bootstrap to complex access control and billing—is handled with high security and developer-centric efficiency.