Create an editor or author account safely

UsersIntermediate~10 min

Before you start

A connected site with the create-user ability enabled, and the update-user ability enabled if you also want the role bump. The agent user must hold the create-users capability, and promote-users for the role change.

Onboarding a new writer usually means making an account and giving it the right level of access. With a governed agent this is deliberately two steps, not one, and that split is the safety feature. The account is created at whatever your site’s default role is, and only then, as a separate approved action, does it get bumped to editor or author.

Because both halves write, this runs create-then-confirm, then a second gated promote.

The prompt
I want to add [Jordan Rivera, [email protected]] as an [editor]. Do this in
two governed steps and pause between them.
First, check that no account already uses that email, then create the user. I
understand the account will land at the site's default role, not the role I
asked for, because create-user always uses the default. Show me the new account
once it exists.
Then, only after I confirm, bump the role to [editor] through the separate user
update step. I know that step needs the promote-users capability and will never
demote the last administrator. At the end, give me the new account id and its
final role.

Why this is safe to run

The design does the guarding for you. Creating a user always lands at the site’s default role and never a role the agent chose, so an agent cannot mint an administrator or an editor in a single call. Turning the account into an editor or author is a distinct ability behind the promote-users capability, and that role change never demotes the last administrator, so you cannot lock yourself out through it.

Both abilities stay off until you enable them, each call is checked against the capability of the user you bound the agent to, and creating a user is treated as a sensitive write in the Activity Log alongside the role change that follows. If anything looks off, the log shows you the new account id and every step taken against it.

Already connected? You do not have to paste this at all. Ask your agent for the “create an editor or author account safely” recipe, give it the name and email, and it runs the same two-step, approve-between flow on your own site.

How it works

  1. Confirm the person's name and email and check no account already uses that email.
  2. Create the account, which lands at the site's default role, never a role the agent picked.
  3. Show you the new account and wait for approval before changing anything about it.
  4. On your approval, bump the role to editor or author through the separate update-user step, which needs the promote-users capability.
  5. Return the new account id and its final role so you can confirm it.

Questions

Can the agent just create an editor directly?
No, and that is on purpose. Create-user always uses the site's default role and never a role the caller chose. Making the account an editor or author is a second, separate step through update-user, which needs the promote-users capability. Two governed steps, not one.
Could this ever affect an existing administrator?
No. The role change never demotes the last administrator, and creating a user does not alter anyone else's account. This recipe only adds a new person and, on your approval, sets their role.