Skip to main content

Manage custom roles

With Custom Roles, you can define granular permissions in Temporal Cloud, giving your team precise control over who can perform specific actions within your account.

What are Custom Roles?​

Custom Roles enable you to define your own roles as bundles of permission primitives (operations/actions) scoped to Temporal Cloud resources (Account, Namespace, Nexus Endpoint, or Connectivity Rule) and assign them to any principal (user, group, service account).

Why use Custom Roles?​

Use Custom Roles when you need more granular access control than the predefined roles provide. Common use cases include:

  • Least-privilege access: Grant users only the permissions they need to perform their job functions.
  • Delegated administration: Allow teams to manage specific Temporal Cloud resources without granting full account administration privileges.
  • Service account security: Create narrowly scoped permissions for automation and integrations, reducing risk if credentials are compromised.

Custom Roles limits​

For more information about the limits of Custom Roles, see Custom Roles limits.

Defining Custom Roles​

Custom Roles are user-defined collections of permissions that grant access to specific Temporal Cloud resources and operations.

Permissions can be scoped to either all resources of a given type or a selected set of resources.

For example, you might want users with the Account Developer role to view all Namespaces for troubleshooting, without allowing them to modify Namespace configuration. To do this, create a Custom Role named NamespaceGlobalReadOnly that grants:

  • cloud.namespace.list, scoped to the Cloud Account
  • cloud.namespace.get, scoped to all Namespace resources
Custom Roles are additive only

A principal (user, user group, or service account) must have a predefined account role (such as developer, or read). Custom Roles define a set of granular permissions and assign them alongside the predefined role. The effective access is the union of both. You cannot use custom roles to narrow down or remove permissions from a predefined role. You also cannot replace a pre-defined role with a custom role.

Delegating Custom Roles​

Custom role administration defaults to the Account Owner, but can be delegated. Account Owners are the primary principals that can manage Custom Roles (that is, they can create, list, update, delete, or assign a Custom Role).

Account Owners can delegate Custom Role administration to other roles such as Global Admin, but this comes with risk. If the Account Owner creates a Custom Role that includes the ability to create, update, or assign Custom Roles, and assigns that role to any other principal, such as Global Admin or Developer, users with that new role can create or modify roles with otehr operations and assign them to themselves or others.

Use caution when delegating Custom Role operations

By default, only the Account Owner can create or assign Custom Roles. The Account Owner can create roles that have permission to create, modify, or assign roles. If the Account Owner assigns these roles to another user, that user will have the ability to create or modify roles. This leads to privilege escalation risk where a user would have the ability to assign themselves or others to a role with any operations, even ones they're not approved for.

The following operations present risk when delegated:

  • cloud.customrole.create
  • cloud.customrole.update
  • cloud.customrole.assign

Available permissions​

Most of the Control Plane operations listed in the API references (HTTP, GRPC) can be assigned to a Custom Role. For the operations that are supported by Custom Roles, see this table.

Create Custom Roles​

To create a Custom Role from the Web UI, select Settings in the left sidebar, and then click the Custom Roles tab on the Settings page.

On the Custom Roles tab, you'll see a list of the roles that have already been defined for your account, 50 to a page. Click the three dots menu to view details about an existing Custom Role, or to edit or delete that role.

Click the Create Custom Role button to create a new role. On the Create Custom Role page, give the Custom Role a name, and optionally a description.

Creating a new custom role

In the Permissions section, you'll assign the appropriate resources and its permissions. The following resources are available for Custom Roles:

  • Account: Permissions scoped to the current account, listed by type.
  • Namespace: Permissions scoped to the selected Namespace, listed by type. You can only assign permissions to Namespaces to which you have access.
  • Nexus Endpoint: Permissions scoped to the selected Nexus Endpoint, listed by type. You much have at least one Nexus Endpoint enabled before you can assign Nexus Endpoint permissions to a Custom Role.
  • Connectivity Rules: Permissions scoped to the selected Connectivity Rules, listed by type.

Account-level permissions apply to the current account. For each of the other resources, you'll need to first select the resource that you want to grant permissions for. Once you select a resource, the list of available permissions will appear, and you can turn them on or off as desired.

At the bottom of the Account tab are permissions that relate to Custom Roles. Here, you can define whether members of the Custom Role you're creating will be able to create, update, or delete Custom Roles.

When you're done assiging permissions to resources, click Create Custom Role at the bottom of the page.

Assigning Custom Roles to users​

Once you have created a Custom Role, it is available on the Identities page to assign to a user or group, the same as the pre-defined Temporal permissions. See How to update an account-level role in Temporal Cloud for more inforamtion.

Modifying a Custom Role​

To modify a Custom Role from the Web UI, select Settings in the left sidebar, and then click the Custom Roles tab on the Settings page.

On the Custom Roles tab, you'll see a list of the roles that have already been defined for your account, 50 to a page. Click the three dots menu of the Custom Role you want to modify and select Edit.

The Edit Custom Role page has the same options as the Create Custom Role page. You can change the Custom Role's name or description, or you can modify any of the current permissions assigned to that Role.

When finished, click Update Custom Role.

Delete a Custom Role​

To delete a Custom Role from the Web UI, select Settings in the left sidebar, and then click the Custom Roles tab on the Settings page.

On the Custom Roles tab, you'll see a list of the roles that have already been defined for your account, 50 to a page. Click the three dots menu of the Custom Role you want to delete and select Delete. A pop-up notification will let you know that the Custom Role has been deleted.