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.
When to use this
Section titled “When to use this”- 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.
Before you start
Section titled “Before you start”- The right page. Open Configure → Access → Assignments. You need
updaterights oniam.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.
1. Open the assignments editor
Section titled “1. Open the assignments editor”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.
2. Assign a role
Section titled “2. Assign a role”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:
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 ofroles.- The hook deduplicates the array and keeps first-occurrence order.
3. Remove a role
Section titled “3. Remove a role”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.
4. Check the result
Section titled “4. Check the result”Re-read the account:
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.
How election works
Section titled “How election works”One role per request
Section titled “One role per request”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.
Election at sign-in
Section titled “Election at sign-in”The sign-in request may carry the election in its role field, as a qualified
id:
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.anonymousrole. The response showsavailable_roles: []with the anonymous role asactive_role; the workspace renders a no-role screen from that pair. See Roles and permission lines for what the anonymous role controls.
Switching during a session
Section titled “Switching during a session”A member switches role without signing in again. The refresh route accepts the new election:
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.
Troubleshooting
Section titled “Troubleshooting”The assignment write answers 403
Section titled “The assignment write answers 403”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.
Sign-in answers 403 Role not assigned
Section titled “Sign-in answers 403 Role not assigned”The election names a role outside the account’s roles array. Assign the role
first, or sign in without the role field.
A member acts with unexpected rights
Section titled “A member acts with unexpected rights”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.
Related
Section titled “Related”- Roles and permission lines — what one role carries.
- Manage accounts — create the account first.
- Auth contexts — the one-role-per-request model.
- Auditing activity — the
acting_roleon every write. - Sign in, MFA, reset your password — the member’s sign-in steps.
- Internals on GitHub: rbac.md, access-assignments.md.