On this page0
Unfamiliar word? See Glossary: words used in these docs. Looking for the tasks in order? Begin at Start Here.
Reference
Included in: All plans. Which Plan Includes What
Personas (Job Blueprints)
What a persona holds, how it is applied when someone joins or changes job, which items Zonitix sets up by itself and which become tasks for IT. The steps on screen are in Create a persona.
If something here is not working as you expect, start with When something goes wrong.
The plain explanation is above. This part is for IT and developers: the exact settings, permission names, API addresses and data fields behind it. Closed: select the heading above to open it. While it is closed, your browser’s find-on-page (Ctrl+F or Cmd+F) does not search this part.
A persona is one row. A person points at it through personaId on their user record. On screen a persona is also called a blueprint, and the API calls a role change a mover.
Endpoints
Session routes on your own instance’s API address, https://<your-instance>-api.zonitix.com. The four routes that say “changes nothing” are safe to call from a confirmation screen.
| Method | Path | Purpose | Auth |
|---|---|---|---|
| GET | /api/v1/user-management/personas | List every persona, by name. | view_users, manage_users or manage_personas |
| POST | /api/v1/user-management/personas | Create a persona. Answers 201 with the saved persona. body the persona fields below | manage_users or manage_personas |
| PUT | /api/v1/user-management/personas/:id | Change a persona. Answers 200 with the saved persona. Send the whole persona: an access or device list left out is saved as empty, and the cost estimates are worked out again from the templates sent. body the persona fields below | manage_users or manage_personas |
| DELETE | /api/v1/user-management/personas/:id | Delete a persona nobody uses. Answers 204. | manage_users or manage_personas |
| POST | /api/v1/user-management/personas/:id/provisioning-plan | Sort a saved persona’s items into automatic steps and IT tasks. Changes nothing. With workflowId, items that workflow leaves out are marked excluded. body { startDate?, workflowId? } returns { persona, cost: { oneTime, monthly }, workflow, startDate, items[], summary } | view_users, manage_users, manage_personas or manage_workflows, or manage_approvals |
| POST | /api/v1/user-management/personas/preview/provisioning-plan | The same sort for a persona sent in the body, saved or not. Changes nothing. body { persona, startDate? } returns { startDate, items[], summary } | view_users, manage_users, manage_personas or manage_workflows |
| POST | /api/v1/user-management/personas/preview/coverage | For up to 200 app names, say whether each would be automatic or an IT task. Changes nothing. body { names[] } returns { coverage: { <name>: { mode, reason, providerType, providerId } } } | view_users, manage_users, manage_personas or manage_workflows |
| POST | /api/v1/user-management/personas/preview/mover-plan | Compare a person’s current persona with a new one. Changes nothing. body { userId, newPersonaId, startDate? } returns { user, from, to, additions[], removals[], kept[], summary, cost: { oldMonthly, newMonthly, monthlyDelta }, noCurrentRole } | manage_users, manage_personas or manage_workflows |
| POST | /api/v1/user-management/personas/mover | Start a role-change run for a person. Answers 201. body { userId, newPersonaId, keep?, revokeGraceDays? } returns { runId, from, to, summary: { grant, revoke, kept } } | manage_users |
| POST | /api/v1/user-management/users/:id/onboard | Start an onboarding run for a person from a persona. Answers 201, or 202 when the account was prepared but something needs attention. body { personaId?, startDate?, managerId? } | manage_users |
What A Persona Holds
| Field | Meaning |
|---|---|
| name | The job’s name. Required and unique; at most 255 characters. |
| description | Free text; at most 255 characters. |
| status | draft or ready. Set to ready when the persona lists at least one access item, licence or device, and to draft on creation when it lists none. |
| accessRequirements | A list of access items with no licence. Empty by default. |
| licenseTemplate | A list of apps and seats. Each entry’s monthly price is added into the monthly estimate. |
| hardwareProvisioning | A list of devices. Each one always becomes an IT task. |
| hardwareTemplate | One-time hardware costs by item, added into the one-time estimate. |
| providerMapping | Keyed by item name. The value is a provider type, the id of one specific connection, or manual to force an IT task. With no entry, the type is worked out from the item’s name. |
| accessGroups | Ids of the Zonitix groups a person in this job joins. |
| accessRoleIds | Ids of the Zonitix permission roles a person in this job is given. Empty by default. |
| autoAssignDepartment | A directory department name. When set, a directory sync that moves someone into that department proposes a role change to this persona. One department can point at only one persona. |
| estimatedOneTimeCost, estimatedMonthlyCost | Worked out by the server from the two templates on every save. Returned as decimal strings. |
Automatic Or A Task For IT
Every access item, licence and device is sorted into one of two modes by the same rule, whether you ask for a preview or start a real run. auto means a connected app or directory sets it up. task means a person does it, with the start date as the due date. The reason on each item says why.
| Mode | Reason text | When |
|---|---|---|
| auto | Connected <type> — auto-provision | The item resolves to an app or directory that is connected, switched on, allowed to write users, and of a type Zonitix can write to. |
| task | Marked manual | The persona’s mapping sets this item to manual. |
| task | No matching provider — IT task | The name does not match any app Zonitix knows how to set up. |
| task | <type> not connected — IT task | Zonitix could set it up, but that app is not connected. |
| task | <type> is connected but read-only (user writes are disabled on the hook) — IT task | The connection is there, but it has been set to read-only. |
| task | <type> not auto-provisionable yet — IT task | Zonitix recognises the app but cannot create accounts in that type. |
| task | More than one directory is connected (<types>) — name the one this role needs in the persona, so nobody is created in the wrong one. IT task | The persona does not say which directory this job uses, so nobody is created in the wrong one. |
| task | No writable directory is connected — IT task | The item asks for a directory account and no directory can be written to. |
| task | Physical device — IT fulfilment | Every device. |
| excluded | Not needed for this pipeline — excluded by the workflow | The workflow named in the request leaves this item out. Nothing is created for it. |
The types Zonitix can create accounts in are: AZURE_AD, OKTA, GOOGLE, LDAP, OPENLDAP, SCIM, AWS, SLACK, GITHUB, ZOOM, ONE_PASSWORD, JIRA, SALESFORCE, BAMBOOHR, ZENDESK, SERVICENOW, DROPBOX. A Google directory stored as GOOGLE_WORKSPACE counts as GOOGLE. A connection of one of these types is used only while it is switched on and allowed to write users. How connections are set up is on Identity Hooks (Directory & App Connections).
The summary counts the items: total, auto, tasks, excluded, excludedLabels (the names of the excluded items), and dueDate.
// Preview a SAVED persona before any run fires. startDate becomes each task's dueDate.
curl -X POST https://<your-instance>-api.zonitix.com/api/v1/user-management/personas/42/provisioning-plan \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $ZX_TOKEN" \
-d '{ "startDate": "2026-09-01" }'
// 200 response — the two piles, plus a summary you can show on the confirm screen:
{
"persona": { "id": 42, "name": "Sales Rep" },
"startDate": "2026-09-01",
"items": [
{ "kind": "access", "label": "Slack", "providerType": "SLACK", "providerId": null,
"mode": "auto", "reason": "Connected SLACK — auto-provision", "dueDate": null },
{ "kind": "hardware", "label": "MacBook Pro 14", "providerType": null, "providerId": null,
"mode": "task", "reason": "Physical device — IT fulfilment", "dueDate": "2026-09-01" }
],
"summary": { "total": 2, "auto": 1, "tasks": 1, "excluded": 0, "excludedLabels": [], "dueDate": "2026-09-01" }
}
// The inline variant is identical minus the persona field — POST the draft itself:
POST /api/v1/user-management/personas/preview/provisioning-plan
{ "persona": { "accessRequirements": ["Slack"], "providerMapping": {} }, "startDate": "2026-09-01" }
Joiners
- Starting onboarding records the persona on the person, adds the persona’s Zonitix groups and roles to them, and creates a run whose steps are the sorted items above. Groups and roles are only added here, never removed.
- Asking twice is safe. If a run is already in progress for the person, the reply says so and no second run is created.
- A
202is not a success. It means the account was prepared but no run was created, or a returning person’s directory account is still disabled. The reply says what to act on. - Setting the persona on the user form records it and, when the user is created, adds the groups and roles. It starts no run, so no apps, licences or devices are set up that way.
Movers: Approval And Revoke-After
- A role change is a run, not an edit. The request compares the old persona with the new one and creates a run of your Mover workflow. The workflow that ships with every instance has two fixed steps, Role Change and Manager Approval; the grant and revoke steps for this person are generated from the comparison and added to the run.
- The person’s persona changes when the run completes, not when it is requested. At that point their Zonitix groups and roles are brought in line: the new persona’s are added, and the old persona’s are removed unless the new persona also lists them.
- Keep list.
keepnames items of the old persona the person should retain, for a handover for example. Those are never revoked by this run. - Revoke-after.
revokeGraceDays(the Revoke old access after field) dates every revoke step that many days later, counted from the start date or, with none, from today. The default is 0. Grants are not delayed. - One at a time. A second role change for the same person while one is waiting answers
409. - From a directory sync. When a sync changes an active person’s department and exactly one persona that is not a draft names that department in
autoAssignDepartment, Zonitix proposes the same run, with an empty keep list and revokes dated 7 days out. It only proposes: the run goes through the same workflow as one a person starts. With no persona naming the department, or more than one, nothing is proposed.
Limits And Refusals
| Status | Cause |
|---|---|
| 400 | A name, description or department longer than 255 characters. On a role change: userId or newPersonaId missing, the person already has that persona, or nothing would be granted or revoked after the keep list. |
| 403 | The persona would give Zonitix groups or roles the caller could not give directly. This is checked when a persona is saved, when it is set on a person, when onboarding is started and when a role change is started. |
| 404 on change, plan, preview and role change | The persona or the person does not exist. |
| 409 on save | Another persona already has that name, or that department already points at another persona. |
| 409 on delete | The persona is still set on people or job postings. The reply carries references: { users, jobPostings }. Move them to another persona first. |
| 409 on role change, code active_mover_run_exists | A role change for this person is already waiting. Finish or cancel it first. |
| 503 on role change | No active Mover workflow exists, so the run cannot be started. |
What Is Audited
| Action | Written when |
|---|---|
| PERSONA_CREATED, PERSONA_UPDATED, PERSONA_DELETED | A persona was saved or deleted. An update lists the fields that were sent. |
| PERSONA_ACCESS_CHANGED | A save set the persona’s Zonitix groups or roles; the entry lists the ids. |
| PERSONA_DELETE_BLOCKED | A delete was refused because the persona is in use, with the counts. |
| ROLE_ESCALATION_BLOCKED | A save, an assignment, an onboarding or a role change was refused because the persona gives access the caller lacks. |
| PERSONA_ACCESS_APPLIED | A persona’s groups and roles were added to a person, when the person was created with the persona or a workflow step applied it. |
| USER_ONBOARDING_STARTED | Onboarding was started for a person, with the persona, the start date and whether a run was created. |
| USER_ROLE_CHANGED | A role-change run was created, by a person or proposed by a directory sync, with the counts granted, revoked and kept. |
| PERSONA_ACCESS_RECONCILED | A role change finished and the person’s Zonitix groups and roles were brought in line with the new persona. |
How runs move from step to step is on How Workflows Run (Orchestration), and permission roles are on Roles & Permissions (RBAC).