Roles & permissions

Every action inside an organization is checked against your role in that organization. ModuleX keeps the model deliberately small: there are two live roles, owner and admin, and the role you hold is verified on every request, not just at sign-in. This page is the exhaustive reference for that model: the live roles, the gate each kind of action requires, the exact errors you get when a check fails, and the edge cases that come from a role being retired mid-life. For the conceptual tour of tenancy and how the role attaches to your membership, see Organizations, roles & membership.

Roles are resolved per request from your membership in the organization named by the X-Organization-ID header. The same role check runs whether the request comes from the app (a Clerk sign-in) or from code (an mx_live_ API key). See Org context & X-Organization-ID for how that header is validated.

The live roles

An organization role is one of exactly two values.

Owner

Assigned to whoever creates the organization. An owner can do everything an admin can, plus a small set of owner-only actions such as removing a member. Owner is the only role that cannot be assigned later.

Admin

Full working access: create, edit, run, and deploy workflows, use the AI Composer and the Assistant, manage knowledge and credentials, schedule runs, and invite teammates. Everyone invited to an organization joins as an admin.

A few rules govern how those roles are set:

The role lives on your organization membership record, with a column default of admin.
Owner is assignable only at organization-creation time. The person who creates the organization becomes its owner; no API can promote another member to owner afterward. Role-changing requests are validated against the pattern ^admin$ at the edge, so owner is rejected as an input value.
An organization can have more than one owner only through ownership transfer mechanics that are not exposed as a public role-update operation today. Treat owner as fixed at creation unless you remove and recreate the organization.

There is a separate, account-level role on the underlying user record (USER versus SUPER_ADMIN) used only by ModuleX platform staff. It is distinct from your organization role and is not something customers assign. This page covers organization roles only.

The member role is retired

ModuleX previously had a third role, member, that granted read-only access. It was retired on 2026-06-20. The live roles are owner and admin only.

There is no member role you can assign. If you see member referenced in an old export, a legacy membership row, or a third-party type definition, treat it as deprecated. New invitations and role changes accept only admin (owner is creation-only), and the role checks below recognize only owner and admin.

Because the role was retired in place rather than fully purged, a few legacy mentions of member can still surface. None of them let you grant the role through a supported path, but they are worth knowing about:

Old membership rows may still carry member

A membership created before 2026-06-20 can still hold the literal value member in the database, and an unfiltered organization listing can still return such rows. The write gates below do not treat member as owner or admin, so a legacy member row has neither admin nor owner permissions on the gated surfaces.

The membership-list filter still accepts member as a query value

GET /auth/me/organizations accepts an optional role filter whose documented values are member, admin, and owner. Passing member filters for legacy rows; it does not create or imply a usable role. Prefer filtering by owner or admin.

The realtime layer still lists member in its role union

The realtime (Socket.io) collaboration server still names member in its internal role union and would grant such a connection read-only canvas access. This only matters for legacy rows; admins and owners get full read and write. See the caveat in Presence, locks & versioning.

How a role is enforced

Every org-scoped route runs the same two-stage check before it does any work:

Membership is verified

ModuleX reads the X-Organization-ID header, confirms you are an active member of that organization, and resolves your role in it. A missing header, an inactive account, or a non-membership stops the request here. See Org context & X-Organization-ID for the membership errors.

The role gate is applied

The route then requires either owner/admin or owner-only, depending on the action. If your resolved role is not high enough, the request is rejected with a 403 before any side effect occurs.

There are three role gates in the backend. Almost every product action uses the admin gate.

any member of the org

Requires only that you are an active member of the organization named in X-Organization-ID. Used for personal, non-privileged actions such as leaving an organization. Resolved by the organization_membership_required dependency.

owner or admin

Requires your role to be owner or admin. This is the gate on the working surfaces: workflows, the AI Composer, the Assistant, schedules, knowledge bases, and credentials. Resolved by the organization_admin_required dependency.

owner

Requires your role to be exactly owner. Reserved for a small set of organization-administration actions, such as removing another member. Resolved by the organization_owner_required dependency.

What each role can do

The table below maps every privileged surface to the role it requires. “Admin” means owner or admin (owners always satisfy the admin gate); “Owner” means owner only.

Surface / action	Minimum role	Notes
Create, list, read, update, delete a workflow	Admin	All builder CRUD is admin-gated.
Run a workflow and stream, resume, or cancel a run	Admin	Includes `POST /workflows/run`, `listen`, `resume`, and `cancel`.
Deploy a workflow and manage deployments & versions	Admin	Deploy, activate, and delete deployments.
Use the AI Composer (generate, edit, save, revert a workflow)	Admin	Every Composer route is admin-gated.
Use the Assistant (start a chat, send messages, resume, cancel)	Admin	Every Assistant route is admin-gated.
Create, update, run, pause, or delete a schedule	Admin	Every schedule route is admin-gated.
Manage knowledge bases and documents, and run searches	Admin	All knowledge routes are admin-gated.
Manage credentials: create, update, delete, test, OAuth2 connect	Admin	All credential routes are admin-gated.
View the organization LLM catalog and org settings	Admin	Catalog, model visibility, and the default Composer model.
Invite a teammate, cancel or resend an invitation, change a member’s role	Admin	Role changes accept only `admin` as the target value.
Remove a member from the organization	Owner	The only routine owner-only product action.
Create an API key and create an organization	Any signed-in user	Not org-role-gated; key creation uses your account identity.
Leave an organization	Any member	Owners cannot leave their own organization.

The Composer, the Assistant, and schedules all require owner or admin. Some source comments describe the chat surfaces as “available to every member” — that comment is inaccurate. As shipped, those surfaces are admin-gated and a legacy member row is rejected with a 403.

Admin can change roles, but not create owners

Promoting or demoting a teammate is an admin action with built-in guardrails. When you call the role-update operation:

The only accepted target role is admin (the request body is validated against ^admin$). You cannot set owner through this route.
You cannot change your own role.
You cannot change the role of an owner.
An admin cannot change the role of another admin; that is an owner-level conflict and is rejected.

These guardrails mean ownership is effectively fixed at creation, and the role surface that an admin can actually move is narrow.

Managing roles and membership

Role and membership management is exposed over REST and works the same from the app or from code. Authenticate every request with your API key as a bearer token plus the organization header, exactly as elsewhere in the API.

# List your organizations and the role you hold in each
curl https://api.modulex.dev/auth/me/organizations?role=admin \
  -H "Authorization: Bearer mx_live_2J9vK4xM7pQ1sR8tU3wY6zB"

# Invite a teammate (joins as admin) — requires owner or admin
curl -X POST https://api.modulex.dev/organizations/invite \
  -H "Authorization: Bearer mx_live_2J9vK4xM7pQ1sR8tU3wY6zB" \
  -H "X-Organization-ID: 8a1f3c2e-9b4d-4e7a-bc11-7d6e5f4a3b2c" \
  -H "Content-Type: application/json" \
  -d '{"invited_email":"teammate@acme.com","role":"admin"}'

# Update a member's role — requires owner or admin; only "admin" is accepted
curl -X PUT https://api.modulex.dev/organizations/8a1f3c2e-9b4d-4e7a-bc11-7d6e5f4a3b2c/users/USER_ID/role \
  -H "Authorization: Bearer mx_live_2J9vK4xM7pQ1sR8tU3wY6zB" \
  -H "X-Organization-ID: 8a1f3c2e-9b4d-4e7a-bc11-7d6e5f4a3b2c" \
  -H "Content-Type: application/json" \
  -d '{"role":"admin"}'

# Remove a member — OWNER ONLY
curl -X DELETE https://api.modulex.dev/organizations/8a1f3c2e-9b4d-4e7a-bc11-7d6e5f4a3b2c/users/USER_ID \
  -H "Authorization: Bearer mx_live_2J9vK4xM7pQ1sR8tU3wY6zB" \
  -H "X-Organization-ID: 8a1f3c2e-9b4d-4e7a-bc11-7d6e5f4a3b2c"

import asyncio
from modulex import Modulex

async def main():
    async with Modulex(
        api_key="mx_live_2J9vK4xM7pQ1sR8tU3wY6zB",
        organization_id="8a1f3c2e-9b4d-4e7a-bc11-7d6e5f4a3b2c",
    ) as client:
        # List your organizations and the role you hold in each
        orgs = await client.auth.organizations(role="admin")
        print(orgs)

asyncio.run(main())

import { Modulex } from "modulex-js";

const client = new Modulex({
  apiKey: "mx_live_2J9vK4xM7pQ1sR8tU3wY6zB",
  organizationId: "8a1f3c2e-9b4d-4e7a-bc11-7d6e5f4a3b2c",
});

// List your organizations and the role you hold in each
const orgs = await client.auth.organizations({ role: "admin" });
console.log(orgs);

Membership and invitation methods have partial SDK coverage. Listing your organizations is available in both SDKs; invitations and role changes may be REST-only on a given SDK version. Check the SDK ⇄ API parity matrix before relying on a specific method, and fall back to a direct REST call when a method is absent.

Inviting teammates

Invited teammates always join as admin. Two things gate an invitation:

Your role must be owner or admin

The invite, cancel, and resend operations are admin-gated. A legacy member row cannot invite.

Your plan must allow teammates

Inviting teammates is a paid-plan entitlement. On a Free plan, the invite is rejected with a 403 carrying the code TEAMMATES_NOT_ALLOWED, prompting an upgrade. The same entitlement is re-checked when the invitee accepts. See Plans & pricing.

Accepting or rejecting an invitation is done by the invited person and requires only that they are signed in; it is not gated on an organization role, because they are not yet a member. Owners cannot leave their own organization, so the last administrative tie to an organization is always an owner.

Errors

Role and membership failures come back as standard FastAPI error envelopes — a JSON object with a detail field. (The flat billing DenialEnvelope documented on Usage gating & limits applies to usage/quota denials on the run, Composer, Assistant, and managed-knowledge surfaces; it is separate from the role errors here. The full taxonomy is on Errors & status codes.)

Status	When	Response `detail`
`400`	The `X-Organization-ID` header is missing on an org-scoped route	`"X-Organization-ID header is required"`
`401`	No or invalid credential	`"Authentication required. Provide Authorization: Bearer token or X-API-KEY header."`
`403`	Active user but not a member of the named organization	`"User is not a member of organization {organization_id}"`
`403`	Member, but not owner/admin on an admin-gated route	`"Admin or owner role required in organization {organization_id}"`
`403`	Owner/admin, but not owner on an owner-only route	`"Owner role required in organization {organization_id}"`
`403`	API key scoped to a different organization than the header	`"API key is scoped to a different organization"`
`403`	Inviting a teammate on a plan without the entitlement	`{"message": "...", "code": "TEAMMATES_NOT_ALLOWED"}`
`400`	An owner attempts to leave the organization	`"Organization owners cannot leave..."`

Show Example: admin-gate 403

A request from a legacy member (or any non-admin) to an admin-gated route such as POST /workflows/run:

{
  "detail": "Admin or owner role required in organization 8a1f3c2e-9b4d-4e7a-bc11-7d6e5f4a3b2c"
}

Show Example: owner-only 403

A request from an admin (not the owner) to remove a member via DELETE /organizations/{organization_id}/users/{user_id}:

{
  "detail": "Owner role required in organization 8a1f3c2e-9b4d-4e7a-bc11-7d6e5f4a3b2c"
}

Edge cases & gotchas

Owner cannot be assigned after creation

The role-update route validates the target role against ^admin$, so owner is never an accepted value. The creator is the owner; there is no supported public operation to promote a second member to owner. Plan ownership at the point you create the organization.

An admin cannot demote or change another admin

Role changes are admin-gated, but an admin acting on another admin is rejected. This keeps admins from removing each other’s access; only the broader account/ownership context resolves such conflicts. You also cannot change your own role.

API-key org scope is enforced on top of your role

An API key can be locked to a single organization. If a request uses that key with a different X-Organization-ID, it is rejected with 403 before the role check even runs. A correctly scoped key still grants only the role you hold in that organization — scoping a key does not elevate it. See Auth model: JWT vs API key.

Realtime role changes can lag behind the database

The realtime collaboration server caches your organization membership and role for a short window (up to about five minutes). A role change made over REST is enforced immediately on REST calls, but a live Socket.io session may not reflect the new role until the cache expires or the connection is re-established. Reconnect to force an immediate re-check. See Presence, locks & versioning.

Organizations, roles & membership

The conceptual model for tenancy, membership, and how your role attaches to an organization.

Org context & X-Organization-ID

How the organization header is validated and how membership is checked on every request.

Auth model: JWT vs API key

The two authentication paths and how API-key organization scoping interacts with roles.

Permissions & limits (Assistant)

Who can use the Assistant and the usage limits that apply on top of the role gate.

Security

Trust

Enterprise

Roles & permissions

The live roles

Owner

Admin

The member role is retired

How a role is enforced

What each role can do

Admin can change roles, but not create owners

Managing roles and membership

Inviting teammates

Errors

Edge cases & gotchas

Organizations, roles & membership

Org context & X-Organization-ID

Auth model: JWT vs API key

Permissions & limits (Assistant)

​The live roles

Owner

Admin

​The member role is retired

​How a role is enforced

​What each role can do

​Admin can change roles, but not create owners

​Managing roles and membership

​Inviting teammates

​Errors

​Edge cases & gotchas

​Related pages

Organizations, roles & membership

Org context & X-Organization-ID

Auth model: JWT vs API key

Permissions & limits (Assistant)

The live roles

The member role is retired

How a role is enforced

What each role can do

Admin can change roles, but not create owners

Managing roles and membership

Inviting teammates

Errors

Edge cases & gotchas

Related pages