This page documents the HTTP API endpoints for managing workspaces and organizations, including creation, member invitations, and permission management. Workspaces serve as organizational containers for workflows, providing multi-tenancy and team collaboration features, while organizations provide a higher-level grouping for enterprise-scale management, seat licensing, and billing.
For workflow-specific operations within a workspace, see Workflow APIs. For authentication implementation, see Authentication APIs.
Workspaces and Organizations form the structural backbone of Sim Studio. The system uses a hierarchical model where users belong to organizations, and organizations contain multiple workspaces.
owner, admin, member), and invitations at the org level.admin, write, read) for workspace resources.Sources: apps/sim/app/api/workspaces/invitations/route.ts85-117 apps/sim/app/api/organizations/[id]/members/route.ts:48-50, apps/sim/app/api/organizations/[id]/members/[memberId]/route.ts:14-18, apps/sim/app/api/organizations/[id]/members/route.ts:178-187
The following diagram illustrates the process from sending an invitation to a user accepting it and gaining access.
Sources: apps/sim/app/api/workspaces/invitations/route.ts186-224 apps/sim/app/api/workspaces/invitations/route.ts83-85 apps/sim/app/api/workspaces/invitations/[invitationId]/route.ts:148-166, apps/sim/app/api/workspaces/invitations/[invitationId]/route.ts:175-180, apps/sim/app/api/workspaces/invitations/[invitationId]/route.ts:33-41
Retrieves all members belonging to a specific organization.
Endpoint: GET /api/organizations/[id]/members
| Parameter | Type | Description |
|---|---|---|
id | Path | Organization ID |
include | Query | Set to usage to include billing data (requires admin) |
Implementation Detail:
The handler joins the member table with the user table and optionally the userStats table for cost tracking via getUserUsageData.
Sources: apps/sim/app/api/organizations/[id]/members/route.ts:22-65, apps/sim/app/api/organizations/[id]/members/route.ts:81-95, apps/sim/app/api/organizations/[id]/members/route.ts:10-11
Updates a member's role within the organization.
Endpoint: PUT /api/organizations/[id]/members/[memberId]
Request Body:
Note: Valid roles are owner, admin, and member. Only owners can promote members to admin.
Sources: apps/sim/app/api/organizations/[id]/members/[memberId]/route.ts:136-157, apps/sim/app/api/organizations/[id]/members/[memberId]/route.ts:196-205
Invitations are created using a randomUUID token and default to a 7-day expiration.
Endpoint: POST /api/workspaces/invitations
Logic Flow:
validateInvitationsAllowed.admin permission for the target workspaceId.workspaceInvitation table with a generated token.WorkspaceInvitationEmail and sends via sendEmail.Sources: apps/sim/app/api/workspaces/invitations/route.ts83-117 apps/sim/app/api/workspaces/invitations/route.ts186-204 apps/sim/app/api/workspaces/invitations/route.ts217-223
The acceptance logic is handled by a GET request to the invitation ID route when a token query parameter is present.
Endpoint: GET /api/workspaces/invitations/[invitationId]?token=...
Key Code Entities:
workspaceInvitation: The database table tracking the invite state.permissions: The table where new access records are inserted upon acceptance.syncWorkspaceEnvCredentials: A utility called after acceptance to ensure the new user has the necessary environment variables for the workspace.Sources: apps/sim/app/api/workspaces/invitations/[invitationId]/route.ts:33-35, apps/sim/app/api/workspaces/invitations/[invitationId]/route.ts:148-166, apps/sim/app/api/workspaces/invitations/[invitationId]/route.ts:175-180
The Invite component manages the user interface for accepting invitations, handling various error states like expired tokens or email mismatches.
The system standardizes error codes to provide user-friendly feedback via the getInviteError function.
| Code | Message |
|---|---|
expired | This invitation has expired. |
email-mismatch | Invitation sent to a different email address. |
already-member | User is already a member of the organization or workspace. |
already-processed | Invitation already accepted or declined. |
already-in-organization | User must leave current org before joining new one. |
Sources: apps/sim/app/invite/[id]/invite.tsx:40-81, apps/sim/app/invite/[id]/invite.tsx:129-161
For system-level operations, Sim Studio uses internal JWT tokens and secret-based CRON authentication.
generateInternalToken: Creates short-lived (5m) tokens for internal API calls using INTERNAL_API_SECRET.verifyCronAuth: Validates requests against env.CRON_SECRET for scheduled tasks.Sources: apps/sim/lib/auth/internal.ts19-36 apps/sim/lib/auth/internal.ts72-99
Members can be removed from a workspace via the DELETE endpoint.
Endpoint: DELETE /api/workspaces/members/[id]
Key Logic:
revokeWorkspaceCredentialMemberships to clean up access.Sources: apps/sim/app/api/workspaces/members/[id]/route.ts:41-45, apps/sim/app/api/workspaces/members/[id]/route.ts:69-71, apps/sim/app/api/workspaces/members/[id]/route.ts:87-92, apps/sim/app/api/workspaces/members/[id]/route.ts:106-106
The client-side application manages workspace and environment state through a series of Zustand stores and an initialization lifecycle.
The useAppInitialization hook triggers initializeApplication, which:
useEnvironmentStore.dataInitialized and appFullyInitialized flags.clearUserData.Sources: apps/sim/stores/index.ts24-55 apps/sim/stores/index.ts107-129 apps/sim/stores/index.ts134-143
The following diagram maps high-level concepts to specific files and functions within the codebase.
Sources: apps/sim/app/api/workspaces/invitations/route.ts1-15 apps/sim/app/api/organizations/[id]/invitations/route.ts:1-14, apps/sim/app/api/help/route.ts15-25 apps/sim/stores/workflows/registry/store.ts9-12 apps/sim/stores/index.ts24-55
Refresh this wiki