Create and manage workspace roles¶

A workspace role groups permissions that people need for their work. For example, an organization can give selected staff permission to view requests without also allowing them to change role definitions. A role's name explains its purpose; its selected permissions determine the actions it can contribute to a person's access.

This guide follows the intended Operations → Roles journey in the WorkOS final designs. The inspected frontend uses demonstration roles and simulated navigation; its Save and status controls do not persist these changes. Use these instructions to review the intended experience and prepare an authorized rollout. Confirm that your release is connected before relying on it for access management.

Understand what a role controls¶

Creating a role, assigning it to someone, and activating it are separate actions. A new role starts Inactive in the current backend. It does not contribute permissions until it is active. Activating a role makes its permissions available to assigned people, subject to their account, workspace, product and other access checks.

Changing a role's permissions affects that shared definition. It can therefore affect several people, including people who are not shown in its Current people panel. Marking a role inactive preserves its assignments and saved permissions. Someone may still receive the same permission through another active role.

A role does not create a staff record, move a person in the organogram, enroll them in a product or purchase a subscription. Product eligibility and the authority to access a particular record remain separate. See Product roles and delegated permissions for the cross-product access rules and the People guide for staff assignments.

For managers and business owners, the practical decision is who needs which actions, who may approve changes and how the organization will verify their effect. Use roles with a clear business purpose and review assignments when responsibilities change. The role directory does not provide a complete access certification, usage measure or financial forecast.

Before you begin¶

• Select the correct workspace and confirm the change with your organization's responsible access administrator. Creating a role requires an active workspace and a usable staff profile belonging to it; a product licence or administrator label alone does not replace those checks.
• Viewing roles, creating roles and editing roles are separate permissions. Access to the directory does not automatically allow changes. Permission choices can be loaded by someone authorized to create or edit a role.
• Agree the role's purpose and the permissions it needs. Keep another authorized administrator available when changing a role that contributes your own access; the current role commands do not establish an automatic safeguard against removing your own management permissions.
• Review existing assignments and the expected impact. The Current people panel is useful context, but it is not the full affected-person list.
• Confirm that your release has connected reads, saves and status updates. Sample names, status labels and confirmations in the inspected preview are illustrative.

Browse and inspect a role¶

1. Open Operations, then Roles.
2. Review Workspace roles. The intended table shows each role's name, its Active or Inactive status, and Open.
3. Select Open for the role you want to inspect.
4. Review the role name, status, grouped Granted permissions and Current people.
5. Use Back to return to the role directory.

An empty directory means no roles were returned by that read. A loading, restricted-access or failed-load state has a different meaning; do not treat one of those states as an empty directory. The current role contract has no search, filters, sorting, pagination, copying, deletion or bulk-action facility. The intended guide does not depend on those controls.

Read Current people correctly¶

Current people shows assigned staff who also have an effective primary placement in the latest active, published organization structure. It displays the person's name, email and placement information. Someone with a role assignment but no such placement can be absent from this panel.

An empty panel does not prove that nobody has the role or that activating, editing or deactivating it has no effect. The permission lookup uses active role assignments without requiring the person to appear in this panel. The panel is also not a complete check of employment status, product eligibility or current access.

If a name or placement is unexpected, compare the person's role assignments in People and their primary placement in the organogram. Ask the relevant administrator to reconcile those facts before using the panel to make an access decision. Directory, role and placement reads may refresh at different times.

Create a role¶

1. From Operations → Roles, select Create role.
2. Enter a clear Role name that describes the responsibility. Check for an existing role with the same purpose before creating another.
3. Under Choose permissions, select at least one permission needed for that responsibility. Use the choices supplied by the connected service; do not rely on the number or sample groups shown in a design preview.
4. Review the complete selection and select Create role. Use Cancel if you do not want to submit it.
5. After a confirmed save, return to the role directory and inspect the saved definition. Verify its name, permissions and Inactive status.
6. Arrange assignments through the separate People access-management journey. Activate the role only when the definition and intended assignments are ready.

The current public create request requires a name and at least one distinct permission, even though an older design note suggests permissions may be optional during creation. A permission appearing in a catalog does not establish that your organization has the associated product entitlement or that the capability is available in your release.

If creation reports that a name already exists, inspect the existing role and either use it or choose a genuinely different responsibility and name. Avoid repeating the same uncertain submission with small spelling changes. After a timeout or lost response, use the recovery guidance before trying again.

Edit a role's name or permissions¶

1. Open the role and select Edit role.
2. Check that the form contains the selected role's actual saved name and permissions. If it contains another role's details or demonstration values, stop and ask for support.
3. Update the Role name and Choose permissions selection. Keep at least one permission selected.
4. Review the entire selection: saving replaces the role's permission set, so an omitted permission is removed from that role.
5. Select Save changes, or Cancel to leave without submitting.
6. Reload the role and verify the saved definition. Confirm affected people's access through the organization's authorized verification process.

Editing does not itself activate the role or change who is assigned to it. Coordinate concurrent changes with other administrators: this flow does not provide an established revision-conflict warning or merge of separate edits. A later complete selection can replace an earlier one.

The backend checks for an existing normalized name during creation, but the inspected edit handler does not repeat that check. Do not rely on rename being protected against duplicate names. Keep names distinct and involve support if two definitions become ambiguous.

Activate a role¶

1. Open the inactive role and review its saved permissions and known assignments.
2. Select Activate.
3. Read the confirmation and confirm activation only when the change is authorized.
4. Reload the role to verify Active, then verify representative assigned people's access.

Activation can affect assigned people beyond those visible in Current people. It does not bypass account, workspace, licensing or record-level checks. The current commands request permission refresh asynchronously; an Active label alone is not proof that every existing session has received the new permissions.

Mark a role inactive¶

1. Open the active role and establish who depends on it, including assignments outside Current people.
2. Select Mark inactive.
3. Read the confirmation and confirm the change.
4. Reload the role to verify Inactive. Check the affected access using your organization's authorized process.

The role's assignments remain saved, which allows the role to be activated again later. Marking it inactive removes this role's contribution when permissions are resolved afresh. It does not automatically sign everyone out, remove other roles, suspend employment or guarantee immediate loss of access in every already-open session.

If urgent access removal is required, use the organization's established account/access response process and ask an authorized administrator to verify the complete result. Do not assume that changing this one status is sufficient.

Recover from failed or uncertain changes¶

When requesting help, provide the workspace, role name, approximate time, intended change and safe error or request reference. Share necessary details only through your organization's approved support channel. Do not include passwords, authorization PINs, tokens or an unnecessary copy of staff information.

Review before operational use¶

Review creation, editing, activation, deactivation and read-only access with representative authorized users. Confirm saved values, correct role identity, complete permission choices, errors, uncertain-save recovery and propagation to affected access. Include a person assigned the role without a current primary placement to confirm that reviewers understand the Current people limitation.

The final designs need updates to permission-group coverage, required create permissions and activation impact wording. The frontend also needs real data and mutations. The initial user/business review and environment verification remain pending; this draft does not claim a completed rollout or audience acceptance.