A Root Organization is an organization from which certain configurations can be inherited by all sub-organizations.
There can only be one root organization in any organization line. For example, if a top level organization is set as the root, no descendants (no matter how removed) can also be set as a root organization.
Setting the Root Organization
To designate an organization as root, a user must have organization administrator privilege (or higher). A root organization can be created in the Management Portal (see Adding a Sub-Organization), or by issuing the org.create API command. An existing organization can also be designated as the root by editing the organization in the Management Portal (see Editing a Sub-Organization), or by issuing the org.update API command.
Attempting to create a sub-organization as root with an ancestor that is already root will fail and return an error. Attempting to update an organization to be root with an ancestor or descendant that is already set as root will fail and return an error.
Root Settings
The root organization defines the configurations that all descendants must adhere to.
| Name | API Field | Description |
|---|---|---|
| Force MFA | forceMfa |
All users of the root organization must have MFA (Multi-Factor Authentication) enabled. If MFA is not enabled for a user, their access to the platform and to most API commands will be restricted. An org which is selected as a root Org will have the RootSettings forceMFA option enabled as soon as the org becomes root. |
Force MFA and User Sessions
When a user accesses an organization where forceMfa has been defined and the user does not have MFA enabled, the user will have the following value returned during the authentication process and set in their session:
"mustEnableMfa": trueThe mustEnableMfa flag will cause the Management Portal to direct the user to their Profile page (see User Profiles) where they can enable MFA. If the user chooses to not enable MFA, they may log out or switch organizations; most other functionality of the platform will be restricted.
If the user does have MFA enabled, the following key will be present and the user will be able to use the platform to the extent that their role(s) allow:
"userMfaEnabled": trueThe user will be able to use the platform as their role(s) allow.