Configuration baselines¶

An MSP runs one console per client. A baseline lets it standardise them: build the configuration once on a reference console, export it as a portable file, and import it into each client's console. The import shows exactly what it would change, resolves everything against the target console, and never applies anything it cannot resolve.

Configuration › Baseline, for an operator with settings.manage:

Action	Also needs	Step-up	Audit
Export	delegations.read (the file contains the roles)	yes	`baseline.exported` (counts only)
Preview an import		no (read-only)	none
Apply an import	delegations.manage when roles, onboarding templates or the leaver template are applied	yes	one `baseline.item_applied` row per item and one `baseline.imported` summary, all with the same correlation id

What a baseline contains¶

A JSON file, schema = steward.baseline/1:

Member	Content
`roles`	Custom roles: name, description, application permissions, delegations (actions, attributes, scope). Built-in roles (Administrators, Super administrator, any role flagged built-in) are never exported.
`onboardingTemplates`	Name, description, target OU, naming patterns, UPN suffix, default attribute values, groups, password and expiry options.
`leaverTemplate`	The steps the leaver dialog turns on by default, the attributes it clears, the note format.
`helpdesk`	Ticket required, caller verification required, verification methods offered.
`passwords`	Generated password mode preselected in the reset dialog (random or passphrase), whether the ready-to-send message includes the password (dictation).
`stepUpMode`	`authenticator`, `password` or `none`.
`branding`	The accent colour only. The instance title names one client's console: it is never part of a baseline.

It never contains a secret, a technical identity, an operator or role membership, a fleet token, a notification channel, a directory setting (domain controllers, CA, managed OUs, protected groups) or any GUID. Two things make it portable:

OUs are paths relative to the managed OU roots: the OU names from a managed OU (included) down, joined with /, for example Corp/Staff or Corp/Staff/Interns. A / or a \ inside an OU name is escaped with \. Paths compare case-insensitively. A role scope keeps its "include sub-OUs" and "exclude" flags.
Groups are names (exact name, case-insensitive). On import a name resolves when exactly one manageable group has it.

Example (shortened):

{
  "schema": "steward.baseline/1",
  "exportedUtc": "2026-10-18T09:00:00Z",
  "roles": [
    {
      "name": "Helpdesk L1",
      "description": "First line",
      "appPermissions": ["audit.read"],
      "delegations": [
        {
          "actions": ["users.read", "users.unlock", "users.password.reset"],
          "scope": [
            { "ou": "Corp/Staff", "includeSubOus": true, "exclude": false },
            { "ou": "Corp/Staff/Executives", "includeSubOus": true, "exclude": true }
          ]
        }
      ]
    }
  ],
  "onboardingTemplates": [
    {
      "name": "Staff",
      "ou": "Corp/Staff",
      "samPattern": "{f}{last}",
      "upnPattern": "{first}.{last}",
      "upnSuffix": "client-a.example",
      "displayPattern": "{First} {Last}",
      "groups": ["GG-Staff-All"],
      "mustChangePassword": true,
      "enable": true
    }
  ],
  "helpdesk": { "ticketRequired": true, "verificationRequired": true, "verificationMethods": ["callback", "manager"] },
  "passwords": { "defaultMode": "passphrase", "messageIncludesPassword": false },
  "stepUpMode": "authenticator",
  "branding": { "accent": "teal" }
}

When something cannot be expressed portably the export leaves it out and says so (for example a role scope whose OU no longer exists).

Importing¶

Upload the file. The server refuses any other schema (baseline_schema_unsupported) and any unexpected member (baseline_invalid): a file of another shape is never half-imported.

Preview. Every item is checked against THIS console with the same rules as its own editor (role rules, template rules and directory checks, leaver and helpdesk rules) and gets an action:

Action	Meaning
`create`	Not on this console yet (roles match by name case-insensitively, templates by exact name).
`update`	Exists and differs: it will be replaced by the baseline's version.
`unchanged`	Already identical.
`skip`	Not applied: a built-in role (`builtin_protected`, never overwritten) or an item you unticked.
`invalid`	Fails a rule (the reasons are listed). It must be fixed in the file or unticked.

Warnings are shown too: a UPN suffix the target does not have is replaced by the target's first suffix, a step-up mode weaker than the current one is flagged: such an import is applied only by a Super administrator who ticks the explicit confirmation (confirmStepUpWeakening: true in the API); anyone else is refused. Roles with powerful grants need a fresh proof even in step-up mode none. 3. Map what does not resolve. Every OU path and group name that does not exist here is listed with the items that use it. Pick the target OU (inside the managed OUs) or search the target group, or untick the items. Mapped groups are checked like any template group (never a privileged, VIP-chain or unmanaged group). 4. Import (step-up). The server plans everything again from the uploaded file (it never trusts the earlier preview) and refuses with baseline_unresolved while any ticked item is invalid or unresolved. Otherwise every item is applied in one transaction: if anything fails, nothing changes. The import is also refused (last_admin) if it would leave no enabled operator holding delegations.manage.

Role memberships are not part of a baseline: after an import, assign the new roles to operators or Teleport role mappings as usual.

API¶

Endpoint	Body
`POST /api/admin/baseline/export`	none; answers `{ "baseline": {...}, "warnings": [...] }`
`POST /api/admin/baseline/preview`	`{ "baseline": {...}, "ouMappings": { "Corp/Old": "<OU objectGUID>" }, "groupMappings": { "GG-Old": "<group objectGUID>" }, "skip": ["role:Name", "template:Name", "leaverTemplate", "helpdesk", "passwords", "stepUpMode", "branding"] }`
`POST /api/admin/baseline/apply`	same as preview, plus `"confirmStepUpWeakening": true` when the baseline lowers the step-up mode (Super administrator only)
`GET /api/admin/baseline/groups?q=`	search manageable groups (mapping)

The preview answers the items, the unresolved OU paths and group names (each with the items using it), the OUs of this console with their paths (mapping choices) and canApply. Uploads may be up to 1 MiB (other API bodies: 64 KiB).