Skip to main content
Everything you do in ModuleX happens inside an organization. It is your shared workspace and your billing boundary at the same time: your workflows, credentials, knowledge bases, plan, wallet, and credits all belong to one organization, and every run is metered against it. This page explains the three ideas you need to work confidently across a team: what an organization is, how ModuleX knows which one you are acting in, and the two roles that decide who can do what. For the request-level detail, follow the links to Org context & X-Organization-ID and Roles & permissions.

The three ideas on this page

Organization

Your workspace and billing boundary. Every resource and every charge belongs to one organization.

Org context

The X-Organization-ID header tells ModuleX which organization a request runs in.

Roles

Each member is an owner or an admin. There is no member role.

The organization: your workspace and billing boundary

An organization is a tenant. It is the line ModuleX draws around your work so that your data, your access, and your bill all stay together and stay separate from everyone else’s.

One workspace for your resources

Workflows, credentials, knowledge bases, and chats live inside an organization. Members of that organization share them.

One boundary for billing

The plan, the credit allowance, and the prepaid wallet belong to the organization — not to an individual. Every run is metered against the organization it runs in.
You can belong to more than one organization — for example a personal workspace and a team workspace — and you can own up to five organizations. Each one is fully separate: switching between them swaps your entire set of resources, plan, and credits.
You never create an account by hand on the API side. ModuleX uses a single identity provider (Clerk) for sign-in, and your ModuleX user and a default personal organization are created automatically the first time you sign in. See Just-in-time provisioning below.

The org context: which organization am I in?

Because you can belong to several organizations, every action has to say which one it applies to. ModuleX calls this the org context, and on the API it is carried by one header: X-Organization-ID. In the ModuleX app you set the org context with the organization switcher, and the app sends the header for you. When you call the API or use an SDK, you set it yourself.

Org context in API and SDK calls

Every org-scoped request carries two headers: your API key as a bearer token, and the organization the request runs in. The example below lists the workflows in one organization.
If you omit X-Organization-ID on an org-scoped endpoint, the request is rejected with a 400 and the message X-Organization-ID header is required. If you are a member of the organization but not allowed to perform the action, you get a 403. See Authentication for how the two headers fit together and Errors & status codes for the full response shapes.
You can also set a default organization once on the client and override it per call. The exact header handling, the SDK precedence rules, and how an API key can be scoped to a single organization are covered in Org context & X-Organization-ID.

Roles: owner and admin

Membership in an organization comes with a role. ModuleX has exactly two live roles.

Owner

The role assigned to whoever creates the organization. Owners can do everything an admin can, plus owner-only actions such as removing members. An owner cannot leave their own organization.

Admin

Full working access to the organization: build and run workflows, use the AI Composer and the Assistant, manage credentials and knowledge, and invite teammates. New members join as admins.
There is no member role. A member role existed in earlier versions of ModuleX and was retired on 2026-06-20. The live roles are owner and admin only, and the API rejects any attempt to invite or set a role other than admin. If you see “member” referenced anywhere, treat it as legacy.
The owner role is assigned only at the moment an organization is created; it is not something you set when inviting or updating a teammate. Every invited or updated member is an admin.

What requires owner or admin

Because the two live roles both have broad working access, most day-to-day actions are available to either role. A few of ModuleX’s most capable surfaces require an owner or admin explicitly, and a small set of governance actions are owner-only.
The following surfaces require the caller to be an owner or admin of the active organization:
  • The AI Composer (turning plain English into a workflow).
  • The Assistant (the agentic chat that calls your tools).
  • Workflow schedules and related management.
  • Organization settings, the LLM catalog, and inviting teammates.
A caller who is authenticated and a member of the organization but lacks the required role receives a 403.
A few governance actions are reserved for the owner:
  • Removing another member from the organization.
  • Owners cannot leave their own organization (transfer ownership or remove the organization instead).
Source-of-truth: this owner/admin model is enforced by the backend on every request. For the per-endpoint permission map — which routes require organization_admin_required versus organization_owner_required — see Roles & permissions. Note that the in-app interface may optimistically show edit controls before the backend confirms your role; the server always enforces the real role on each call.

How you get your first organization

You do not sign up through a ModuleX form. The first time you sign in, ModuleX provisions everything you need automatically — this is just-in-time (JIT) provisioning.
1

You sign in

You authenticate through ModuleX’s identity provider (Clerk). The backend verifies your token; there is no separate ModuleX password or login endpoint.
2

Your user and a personal organization are created

On your first valid sign-in, ModuleX creates your user record and a personal default organization, and makes you its owner — all in one step, so a second concurrent request never creates a duplicate.
3

Your workspace is seeded

The new organization is seeded with sensible defaults so you can start immediately, and you land in it as the active org context.
Your personal organization is named from the first available of your first name, your username, or the part of your email before the @. If none is available, it is named My Workspace.
JIT provisioning happens for sign-in (your user identity). It does not apply to API keys: a key cannot exist before your user does, and creating an API key requires signing in first. See Quickstart to create your first key.

Working as a team

When you are ready to collaborate, you add people to an organization by inviting them.
1

An owner or admin sends an invite

Invite a teammate by email. They join as an admin. Each invitation is valid for 7 days.
2

The invitee accepts

Only the invited email address can accept the invitation. Once accepted, they become a member of the organization with the admin role.
3

They appear in your organization

The new admin shares the organization’s workflows, credentials, knowledge, and billing. Owners can later remove a member; admins cannot.
Inviting teammates is a paid capability. On the Free plan, sending an invite is declined with a 403 and the reason TEAMMATES_NOT_ALLOWED. Upgrade to Pro or higher to invite teammates. See Plans & pricing for what each plan includes.

How this connects to the rest of ModuleX

Org context & X-Organization-ID

The request-level detail: how the org context header is read, how API-key org scope is enforced, and what happens when it is missing.

Roles & permissions

The per-endpoint permission map — exactly which actions require owner or admin.

Credits & the billing model

How managed usage is metered in credits against the organization, and where the billing gate applies.

Private & org chat

How chats can be kept personal or shared across the organization.