Documentation menu

Users reference

Org user management (org-scoped).

GET/users

List org users (manager+)

Parameters

NameInTypeRequiredDescription
X-Organization-IdheaderstringoptionalTarget organization ObjectId; required for APP_ADMIN and SUPPLIER callers and ignored (must match the caller's own org) for org admins, managers, and users.
pagequeryintegeroptionalPage number to retrieve (1-based); integer, minimum 1, defaults to 1.
limitqueryintegeroptionalPage size (number of records per page); integer, minimum 1, maximum 100, defaults to 25.

Responses

  • 200Paginated users.
  • 401Missing/invalid token.
  • 403Authenticated but not allowed (role or cross-org).
POST/users

Invite a user into the org (admin). organizationId is forced from the caller.

Parameters

NameInTypeRequiredDescription
X-Organization-IdheaderstringoptionalTarget organization ObjectId; required for APP_ADMIN and SUPPLIER callers and ignored (must match the caller's own org) for org admins, managers, and users.
pagequeryintegeroptionalPage number to retrieve (1-based); integer, minimum 1, defaults to 1.
limitqueryintegeroptionalPage size (number of records per page); integer, minimum 1, maximum 100, defaults to 25.

Request body UserInvite (required, application/json)

Responses

  • 201Invited user (PENDING, no Cognito until acceptance).
  • 400Request body/params failed validation.
  • 401Missing/invalid token.
  • 402Plan quota reached for this resource (code `QUOTA_EXCEEDED`).
  • 403Authenticated but not allowed (role or cross-org).
  • 409Conflict.
  • 429Rate limit exceeded.
GET/users/{id}

Get an org user (manager+)

Parameters

NameInTypeRequiredDescription
idpathstringrequiredObjectId of the target user in the path.
X-Organization-IdheaderstringoptionalTarget organization ObjectId; required for APP_ADMIN and SUPPLIER callers and ignored (must match the caller's own org) for org admins, managers, and users.

Responses

  • 200The user.
  • 400Request body/params failed validation.
  • 401Missing/invalid token.
  • 403Authenticated but not allowed (role or cross-org).
  • 404Not found (or not in the caller's org).
PATCH/users/{id}

Update an org user (admin)

Parameters

NameInTypeRequiredDescription
idpathstringrequiredObjectId of the target user in the path.
X-Organization-IdheaderstringoptionalTarget organization ObjectId; required for APP_ADMIN and SUPPLIER callers and ignored (must match the caller's own org) for org admins, managers, and users.

Request body UserUpdate (required, application/json)

Responses

  • 200Updated user.
  • 400Request body/params failed validation.
  • 401Missing/invalid token.
  • 403Authenticated but not allowed (role or cross-org).
  • 404Not found (or not in the caller's org).
  • 429Rate limit exceeded.
DELETE/users/{id}

Remove a user (admin). Blocks self-delete + last-admin delete.

Parameters

NameInTypeRequiredDescription
idpathstringrequiredObjectId of the target user in the path.
X-Organization-IdheaderstringoptionalTarget organization ObjectId; required for APP_ADMIN and SUPPLIER callers and ignored (must match the caller's own org) for org admins, managers, and users.

Responses

  • 204Deleted.
  • 400Request body/params failed validation.
  • 401Missing/invalid token.
  • 403Authenticated but not allowed (role or cross-org).
  • 404Not found (or not in the caller's org).
  • 409Conflict.
  • 429Rate limit exceeded.
PATCH/users/{id}/status

Activate/deactivate an org user (admin)

Parameters

NameInTypeRequiredDescription
idpathstringrequiredObjectId of the target user in the path.
X-Organization-IdheaderstringoptionalTarget organization ObjectId; required for APP_ADMIN and SUPPLIER callers and ignored (must match the caller's own org) for org admins, managers, and users.

Request body object (required, application/json)

Responses

  • 200Updated user.
  • 400Request body/params failed validation.
  • 401Missing/invalid token.
  • 403Authenticated but not allowed (role or cross-org).
  • 404Not found (or not in the caller's org).
  • 409Conflict.
  • 429Rate limit exceeded.

User schema

FieldTypeRequiredDescription
_idstringoptionalServer-generated unique identifier (MongoDB ObjectId) of the user; read-only.
firstNamestringoptionalThe user's first name, labelled "First Name" in the UI and required when sending an invite.
lastNamestringoptionalThe user's last name, labelled "Last Name" in the UI and required when sending an invite.
emailstring (email)optionalThe user's email address, labelled "Email" / "Email Address", used as the unique login identity and required when sending an invite.
companyNamestringoptionalOptional company name for the user, shown as the "Company" field on a supplier's own profile.
profileImagestringoptionalOptional URL of the user's profile image; falls back to a default avatar when unset.
roleAPP_ADMIN | ORGANIZATION_ADMIN | ORGANIZATION_MANAGER | ORGANIZATION_USER | ORGANIZATION_SUPPLIERoptionalThe user's platform role — one of APP_ADMIN, ORGANIZATION_ADMIN, ORGANIZATION_MANAGER, ORGANIZATION_USER, or ORGANIZATION_SUPPLIER (displayed as Admin/Manager/User/Supplier) — restricted on invite to ORGANIZATION_ADMIN, ORGANIZATION_MANAGER, or ORGANIZATION_USER.
organizationIdstringoptionalReference to the organization that owns the user (null for suppliers or pre-organization users); server-controlled on invite — forced from the caller's tenant context and never read from the request body.
statusUSER_ACTIVE | USER_DEACTIVEoptionalThe user's account status — USER_ACTIVE ("Active") or USER_DEACTIVE ("Inactive").
invitationStatusstringoptionalWhether and how the user accepted their invitation — stored as USER_INVITATION_STATUS_PENDING, USER_INVITATION_STATUS_ACCEPTED, or USER_INVITATION_STATUS_SELF_SIGNUP (shown in the UI as Pending / Accepted / Self Signup).
onboardedbooleanoptionalWhether the user has completed onboarding; server-controlled.
createdAtstring (date-time)optionalServer-generated timestamp of when the user was created, displayed as the "Created Date"; read-only.

UserInvite schema

FieldTypeRequiredDescription
firstNamestringrequiredThe user's first name, labelled "First Name" in the UI and required when sending an invite.
lastNamestringrequiredThe user's last name, labelled "Last Name" in the UI and required when sending an invite.
emailstring (email)requiredThe user's email address, labelled "Email" / "Email Address", used as the unique login identity and required when sending an invite.
roleORGANIZATION_ADMIN | ORGANIZATION_MANAGER | ORGANIZATION_USERrequiredThe user's platform role — one of APP_ADMIN, ORGANIZATION_ADMIN, ORGANIZATION_MANAGER, ORGANIZATION_USER, or ORGANIZATION_SUPPLIER (displayed as Admin/Manager/User/Supplier) — restricted on invite to ORGANIZATION_ADMIN, ORGANIZATION_MANAGER, or ORGANIZATION_USER.
companyNamestringoptionalOptional company name for the user, shown as the "Company" field on a supplier's own profile.
userGroupIdarray of stringoptionalOptional array of UserGroup ids assigning the user to one or more user groups (frontend label "User Group"); each referenced group must belong to the caller's organization.

UserUpdate schema

FieldTypeRequiredDescription
firstNamestringoptionalThe user's first name, labelled "First Name" in the UI and required when sending an invite.
lastNamestringoptionalThe user's last name, labelled "Last Name" in the UI and required when sending an invite.
companyNamestringoptionalOptional company name for the user, shown as the "Company" field on a supplier's own profile.
userGroupIdarray of stringoptionalOptional array of UserGroup ids assigning the user to one or more user groups (frontend label "User Group"); each referenced group must belong to the caller's organization.