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 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.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.
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.Actions that require owner or admin
Actions that require owner or admin
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.
403.Actions that are owner-only
Actions that are owner-only
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.
@. 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.
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.