# Roles and permissions
Users and teams in Cortex can be assigned to a role which permits or limits the ability to perform specific actions within Cortex. These actions range from creating API keys and adding integrations to editing Scorecards and creating entities. Roles allow you to ensure that only authorized individuals can make high-level changes to your workspace. You can use the [default roles](#default-roles) or you can [create custom roles](#custom-roles).
If a user is assigned to more than one role, they will retain the permissions of the least restricted assigned role. For example, if a user is assigned a `Manager` role and they are a member of a team assigned the `Admin` role, then they will have admin permissions throughout Cortex. Using custom roles may introduce other permissions that supersede default roles.
If a user does not have permission to perform an action, the option will not appear for them.
## Roles in Cortex
### Default roles
When you first access your Cortex account, the following roles are available by default:
* **Admins:** Admins are the owners of the workspace. They have global access to everything within Cortex: settings, Scorecards, and entities.
* **Managers:** Managers have most of the same abilities as admins, but cannot modify permissions or other settings. Managers can create and edit Scorecards, entities, and teams.
* **Users:** Users cannot modify settings, nor can they edit or create Scorecards. Users can edit and create entities and teams.
* **Viewers:** Viewers cannot create or edit anything within the workspace. This is a read-only role.
The following table shows which permissions are associated with the default user roles in Cortex. Note that you can add each of these permissions to [custom roles](#custom-roles).
| Permission | Viewer | User | Manager | Admin |
| ------------------------------------------------------------------------- | :----: | :--: | :-----: | :---: |
| View CQL reports | ✓ | ✓ | ✓ | ✓ |
| View initiatives | ✓ | ✓ | ✓ | ✓ |
| View onboarding management | ✓ | ✓ | ✓ | ✓ |
| View Scorecards | ✓ | ✓ | ✓ | ✓ |
| View catalogs | ✓ | ✓ | ✓ | ✓ |
| Edit and create entities | | ✓ | ✓ | ✓ |
| Archive and delete entities | | ✓ | ✓ | ✓ |
| Edit and create entity types | | ✓ | ✓ | ✓ |
| Edit CQL reports | | ✓ | ✓ | ✓ |
| Edit initiatives | | ✓ | ✓ | ✓ |
| Configure Scaffolder templates | | ✓ | ✓ | ✓ |
| Run the Scaffolder | | ✓ | ✓ | ✓ |
| Run query builder | | ✓ | ✓ | ✓ |
| View GitOps logs | | ✓ | ✓ | ✓ |
| View Workflows | | ✓ | ✓ | ✓ |
| View Workflow runs | | ✓ | ✓ | ✓ |
| Execute Workflow runs | | ✓ | ✓ | ✓ |
| View Scorecard exemptions | | ✓ | ✓ | ✓ |
| View Eng Intelligence | | | ✓ | ✓ |
| Configure Eng Intelligence custom metrics | | | ✓ | ✓ |
| Configure Eng Intelligence | | | ✓ | ✓ |
| Configure identity mappings | | | ✓ | ✓ |
| Edit and create Scorecards | | | ✓ | ✓ |
| Edit, create, and delete catalogs | | | ✓ | ✓ |
| Edit Eng Intelligence custom metric data | | | ✓ | ✓ |
| Edit Workflows | | | ✓ | ✓ |
| Run re-evaluation of Scorecards | | | ✓ | ✓ |
| View audit logs | | | | ✓ |
| View breaking API changes | | | | ✓ |
| View notification logs | | | | ✓ |
| View roles | | | | ✓ |
| Configure appearance | | | | ✓ |
| Configure catalog | | | | ✓ |
| Configure custom metrics | | | | ✓ |
| Configure discovery audit events | | | | ✓ |
| Configure entity verification periods | | | | ✓ |
| Configure integrations | | | | ✓ |
| Configure notifications | | | | ✓ |
| Configure plugin appearance | | | | ✓ |
| Configure Scorecard exemptions | | | | ✓ |
| Edit, create, and delete API keys | | | | ✓ |
| Edit custom metric data | | | | ✓ |
| Edit initiatives | | | | ✓ |
| Edit plugins | | | | ✓ |
| Edit plugin proxies | | | | ✓ |
| Edit, create, and delete secrets | | | | ✓ |
| Enable entity dependency discovery | | | | ✓ |
| Enable onboarding management | | | | ✓ |
| Execute notification logs | | | | ✓ |
| Configure IP allowlist | | | | ✓ |
| Configure OpenID Connector and SCIM | | | | ✓ |
| Configure roles | | | | ✓ |
| Configure settings | | | | ✓ |
| [Run query builder with third-party integrations](#user-content-fn-1)[^1] | | | | ✓ |
### Custom roles
Cortex gives you the ability to create custom roles with granular permissions so users have the access they need. Learn more in the [Custom Roles documentation](https://docs.cortex.io/configure/settings/managing-users/permissioning/custom-roles).
### Permissioning in Workflows
In addition to the granular permissions listed on this page that apply to [Workflows](https://docs.cortex.io/streamline/workflows), it is also possible to:
* Configure specific users, teams, or roles who are allowed to run a Workflow
* Require a user to be an Owner or Editor of an entity in order to run a workflow
These configurations are described in more detail in the [Workflow documentation](https://docs.cortex.io/streamline/workflows#step-2-configure-your-workflow-settings) under "Step 2: Configure your Workflow settings."
## Viewing and assigning roles
### View roles
In [**Settings > Roles and permissions**](https://app.getcortexapp.com/admin/settings/permissions) in Cortex, users with the Admin role can view a list of all users in the workspace and their assigned roles. On this page, you can also assign roles and create custom roles.
### Filter the list
* To filter the list by role, click **Filter** in the upper right corner of the user list, then select and apply filters.
* To filter the list by user, click the magnifying glass icon in the upper right corner of the list, then type in a name.
### Assign role to a user
To change an existing role or add a role to a user:
1. On the [Roles and permissions page](https://app.getcortexapp.com/admin/settings/permissions), locate the user in the Users list.
2. Click into the Roles column that user.
3. Search for and select the desired role from the dropdown list.\
4. To remove a role, click the **X** within the role name for that user.
### Assign role to a team
Team roles allow you to assign the team permissions to a set of users all at once. When you add a new member to a team, Cortex will automatically assign the team role to them.
To set team roles:
1. Navigate to [**Settings > Roles and permissions**](https://app.getcortexapp.com/admin/settings/permissions?userManagementTab=Teams), then click the **Teams** tab.
2. Click **Add team with custom roles**.
3. In the side panel, select a team and a team role.
* The teams listed here are populated from your team source (e.g., Okta, GitHub teams, Slack)\
4. At the bottom of the side panel, click **Set roles**.
## Adding and removing Cortex users
### Review users
At the top of the [Roles and permissions settings page](https://app.getcortexapp.com/admin/settings/permissions), you can see the total number of seats, the number of users who have logged in to your instance, the number of users who have only received notifications but have not logged in, and the number of available seats remaining. You can also view this information in the [About page](https://app.getcortexapp.com/admin/settings/about) under Workspace settings.
### Set a default role for new users
To set a default role for all new users provisioned for your workspace:
1. At the top of the [Roles and permissions settings page](https://app.getcortexapp.com/admin/settings/permissions), click into the field under "Default roles."
2. Select the desired role.
### Add a user
To add a new user to the platform, first direct the user to attempt to log in to your organization's Cortex account. If the user has the appropriate email domain, they will be added automatically upon login.
If the user sees an "access denied" error, this indicates that the user is not authorized to access the app via your SSO tool.
#### **Add a secondary domain**
Cloud customers who need to add a secondary email domain should contact for assistance. This restriction does not apply to self-hosted customers.
### Remove a user
To delete a user:
1. In the list of User permissions, locate the user you need to delete.
2. Click the trash icon for the user.
3. In the confirmation modal, click **Delete**.
#### What is retained
When a user is deleted, all data created by the user — such as Scorecards, custom entities, Workflows, and other configuration — will remain in Cortex and continue to function normally. However, any personal access tokens created by the user will be permanently removed.
{% hint style="warning" %}
If any integrations or automation scripts depend on a deleted user's personal access token, they will stop working. Update those integrations to use a different token before deleting the user.
{% endhint %}
#### Ownership and team membership
Deleting a Cortex user only removes their ability to log in and their personal access tokens. It does **not** automatically remove their email from:
* **Entity ownership fields** — such as service owners or business owners defined in the Cortex UI or via `x-cortex-owners` in YAML
* **Team membership** — defined in the Cortex UI, YAML, or synced from external systems (e.g., GitHub, PagerDuty, Opsgenie)
* **Notification targets** — any notification rules, Workflow steps, or on-call references that use the user's email
Ownership and team membership are stored independently from user accounts. To fully remove a deleted user as an owner or team member, you must update those fields separately — either in the Cortex UI, in your YAML definitions, or in the external system that syncs that data.
#### Visibility of deleted users on teams
Depending on your workspace configuration, deleted users may or may not remain visible on Team pages after their account is removed. Team membership is stored separately from user accounts and can be controlled by workspace-level settings.
{% hint style="info" %}
Contact [Cortex Support](mailto:help@cortex.io) if you need deleted users to remain visible on teams for ownership tracking purposes.
{% endhint %}
#### Reactivation
If a deleted user later regains access to your identity provider (for example, Okta or Google) and logs back into Cortex with the same email address, a **new** Cortex user account will be created. They will be assigned the workspace's default role. Any ownership or team membership that still references their email will continue to be associated with them automatically — no manual re-linking is required.
If an individual has left your organization entirely and is no longer a user in your identity provider, they will not be able to regain access to your organization's Cortex account.
[^1]: This permission is scoped to admins by default to avoid issues with rate limiting, but it can be added to a custom role.
