Skip to content

Assigning roles and role election

An account holds roles in its roles array. A request never merges them: it runs under exactly one elected role. This page shows how an administrator assigns and removes roles, and how the election works at sign-in and at refresh.

  • You hire a member and must give them their working roles.
  • You move a member to another team with different rights.
  • You must answer why a member acts under one role when they hold three.
  • The right page. Open Configure → Access → Assignments. You need update rights on iam.Account.
  • The guard. The role authority guard applies: you can only assign roles at or below your own elected level. See Roles and permission lines.

Open Configure → Access → Assignments. The editor has two modes:

Mode What it shows What it writes
Role Pick a role, see its members. The roles array of each account you add or remove.
Account Pick an account, see its roles. The roles array of that account.

Both modes share one write path. The page URL is deep-linkable, for example /Configure/access/assignments?mode=account&account=<id>; the state survives a reload.

In the account mode, search the account by email, then add one or more roles. Each save issues one update on the account document, the same as a manual PATCH:

Terminal window
curl -k -X PATCH -H "Authorization: Bearer $FACET_API_KEY" \
-H "Content-Type: application/json" \
-d '{"roles": ["iam.Roles.editor", "iam.Roles.comment_author"], "default_role": "iam.Roles.editor"}' \
"https://facet.localhost:3443/Api/iam/Account/01J8Z0A7G3Q5M2X9K4T6VBNR8D"

Replace the role ids and the account id with your values. The answer is the updated account document.

The rules the write enforces:

  • Every role in the final array must exist and be live.
  • Every role must sit at or below your level.
  • default_role, when set, must be a member of roles.
  • The hook deduplicates the array and keeps first-occurrence order.

Select Remove on the role row, or remove it from the array. The write follows the same rules. You cannot remove yourself from a role above your level — the target-protection rule blocks the write.

Re-read the account:

Terminal window
curl -k -H "Authorization: Bearer $FACET_API_KEY" \
"https://facet.localhost:3443/Api/iam/Account/01J8Z0A7G3Q5M2X9K4T6VBNR8D"

The roles array shows the assigned ids. The member sees the new role at their next sign-in or token refresh.

Roles never merge. An account with editor and viewer acts under one of them per request. The effective permission set is exactly one role’s lines. Cross-role scope reconciliation has no non-surprising answer, so Facet does not attempt it. See Auth contexts for the model.

The sign-in request may carry the election in its role field, as a qualified id:

Terminal window
curl -k -X POST -H "Content-Type: application/json" \
-H "X-Requested-With: XMLHttpRequest" \
-d '{"email": "ana@example.tld", "password": "PASTE-THE-PASSWORD", "role": "iam.Roles.editor"}' \
"https://facet.localhost:3443/Api/iam/login"

The resolution order: the explicit election, then default_role, then the first assigned role. An election of a role the account does not hold answers 403. The sign-in, refresh, and me responses all carry the pair:

  • active_role — the elected role id.

  • available_roles — the assigned role ids, the list a member can switch between.

    A roleless account runs under the seeded iam.Roles.anonymous role. The response shows available_roles: [] with the anonymous role as active_role; the workspace renders a no-role screen from that pair. See Roles and permission lines for what the anonymous role controls.

A member switches role without signing in again. The refresh route accepts the new election:

Terminal window
curl -k -X POST -H "Content-Type: application/json" \
-H "X-Requested-With: XMLHttpRequest" \
-d '{"role": "iam.Roles.viewer"}' \
"https://facet.localhost:3443/Api/iam/refresh"

The route answers 403 Role not assigned when the account does not hold the role, and 403 Role not found or disabled when the role document does not exist. The workspace sidebar exposes the same switch in its Switch Role menu. The new role’s permission manifest rides the response, so the interface narrows at once.

Check the level: you can only assign roles at or below your elected level, and you cannot edit an account whose role ceiling is above your own.

The member sees nothing new after the assignment

Section titled “The member sees nothing new after the assignment”

Roles apply at the next sign-in or refresh. Ask the member to refresh, or switch role once.

The election names a role outside the account’s roles array. Assign the role first, or sign in without the role field.

Ask which role they elected. One role applies per request; the rights may come from a wider role than you expect. The audit log names the acting role on every write — see Auditing activity.