Skip to content
RunWhen

Users & Access Control

RunWhen controls access at the workspace level: every person (or group) is granted a role on a workspace, and that role determines what they can see and do. This page covers how users sign in, how to add them to a workspace, and the roles you can assign.

Identities

RunWhen uses an email address as a user’s identity, and supports:

  • Locally generated accounts (self-registration)

  • Social accounts (self-registration), for GitHub, Google, and GitLab

  • Enterprise Single Sign-On (OIDC and SAML)

A user can exist on the platform without belonging to any workspace. Access is only granted once they are added to a workspace with a role (below).

Roles

Each workspace member is assigned one role. Roles map to what a person needs to do:

RoleDescription
ReadView the workspace — SLXs, issues, run sessions, and reports. No changes, no task execution.
Read and RunView, plus run tasks and runbooks directly on demand.
Read and Run with AssistantsView, plus run tasks only through an AI Assistant they have been granted access to — they cannot run tasks directly.
Read/WriteView and edit workspace configuration — SLXs, Rules, Commands, Knowledge, and secrets.
AdminFull control, including managing users, access, integrations, and runners.

Admin is required to manage access. Only Admins can add or remove users, change roles, or edit workspace settings. Grant Admin sparingly.

About “Read and Run with Assistants.” This role does not grant direct task execution. The user can only run tasks via an AI Assistant, and only the assistants they have been explicitly granted access to (through the assistant’s allow-list of users or groups). Use it to let people drive automation through a curated, guard-railed assistant without giving them free rein to run any task.

Add users to a workspace

Adding a user requires the Admin role on the workspace.

  1. Open the workspace and go to Configuration → Users.
  2. Click Add User.
  3. Choose User, enter the person’s email address (existing users in your network autocomplete), and pick a Role.
  4. Click Add User to stage the entry, then Save to apply.

If the email does not yet have a RunWhen account, the platform sends an invitation email. The user gains access once they accept and sign in (their identity must match the invited email).

To change a member’s access, pick a different Role from the dropdown next to their name and Save. To remove someone, click the delete icon on their row and Save.

Group-based access (SSO only)

You can grant access to an entire group instead of listing individuals — useful for onboarding teams at scale.

Groups are SSO-only. RunWhen does not have local or platform-managed groups. A group only works if your identity provider asserts it in the login token (the group claim). RunWhen does not create or store group membership itself; it reads it from each user’s SSO token at login.

Group entries use the format idp-name@group-name, where:

  • idp-name is the name of your configured SSO connection (set during onboarding), and
  • group-name is the group exactly as your IdP emits it in the claim.
  1. Configure your IdP to include a group claim in the SSO token. Group claims and your idp-name are mapped during onboarding — see Single Sign On and do not guess attribute names.
  2. In the workspace, go to Configuration → Users → Add User.
  3. Switch the type to Group, enter the group as idp-name@group-name, and choose a Role.
  4. Save.

Example. Say your IdP connection is named okta and it sends a groups claim like:

{ "email": "alice@example.com", "groups": ["platform-sre", "all-engineering"] }

To give the on-call SRE team permission to view and run tasks, add a Group entry named okta@platform-sre with the Read and Run role. Every user whose SSO token includes the platform-sre group from the okta connection is granted that role automatically — no per-user entry required.

Because group membership is read from the IdP at login, directory changes (adding or removing someone from platform-sre) take effect on that user’s next sign-in. Removing the group entry from the workspace revokes access for everyone in it.

Manage access programmatically

Workspace access can be managed through the API, which is useful for bootstrapping workspaces or reconciling membership from your own systems (HR/IdP, Terraform, CI). Membership is a property of the workspace: update the workspace’s permissions list, where each entry is a user (email) or group plus a role.

{
  "permissions": [
    { "user": "alice@example.com", "role": "admin" },
    { "user": "bob@example.com",   "role": "readandrunwithassistant" },
    { "group": "okta@platform-sre", "role": "readandrun" }
  ]
}

The role values are admin, readwrite, readandrun, readandrunwithassistant, and readonly. The update replaces the full permission set, so always send the complete desired list; users without an existing account are invited by email. The request must be authenticated as an Admin of the workspace. See the API Reference and the Managing Context as Code (GitOps) guide for authenticating a pipeline.

Service accounts (automation)

For non-human access — CI pipelines, scripts, runners — use a service account or Personal Access Token rather than a user identity. Service accounts authenticate to the API and are the recommended way to reconcile context and tasks from a pipeline. See Managing Context as Code (GitOps) for obtaining and using a token, and Kubeconfigs & Service Accounts for runner-side credentials.