Add documentation for Custom Roles feature by brianmacdonald-temporal · Pull Request #4293 · temporalio/documentation

brianmacdonald-temporal · 2026-03-13T19:10:31Z

What does this PR do?

Adds documentation for the Custom Roles feature

Notes to reviewers

┆Attachments: EDU-6050 Add documentation for Custom Roles feature

vercel · 2026-03-13T19:10:38Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
temporal-documentation	Ready	Preview, Comment	May 29, 2026 8:26pm

github-actions · 2026-03-13T19:11:01Z

📖 Docs PR preview links

Cloud

Co-authored-by: Ben Echols <benjamin.echols@temporal.io>

…ation into custom-roles

Fixing broken links

LutaoX · 2026-04-07T20:44:13Z

+
+For more information about the limits of Custom Roles, see [Custom Roles limits](/cloud/limits#custom-role-limits).
+
 ## Defining Custom Roles


Can we also somewhere add the naming standard/convention? See information below
- Allowed characters: a-z A-Z 0-9 _ -
- Not allowed: space
- Special Chars only _ and -
- Max length: 64 characters
- Min Length: 1 character
- Unique per account: NO

LutaoX · 2026-06-02T21:13:51Z

+## What are Custom Roles?
+
+Custom Roles enable you to define your own roles as bundles of permission primitives (operations/actions) 
+scoped to applicable resources (namespaces or account objects) and assign them to any 


Suggested change

scoped to applicable resources (namespaces or account objects) and assign them to any

scoped to Temporal Cloud resources (e.g. [Account](https://docs.temporal.io/cloud/manage-access#temporal-cloud-accounts), [Namespace](https://docs.temporal.io/namespaces), [Nexus Endpoint](https://docs.temporal.io/nexus/endpoints), [Connectivity Rule](https://docs.temporal.io/cloud/connectivity#connectivity-rules) and assign them to any

LutaoX · 2026-06-02T21:22:30Z

+
+Temporal Cloud offers a set of predefined [account-level roles and Namespace-level permissions](https://docs.temporal.io/cloud/users#account-level-roles). 
+These roles are sufficient for many Temporal use cases, but can't cover all combinations of  least privilege, delegation, and automation-safe permissions often required in large enterprises.
+


add what you had in the description here? I like that it is very straightforward and easy to understand:
"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."

LutaoX · 2026-06-02T21:23:50Z

+id: custom-roles
+title: Manage custom roles
+sidebar_label: Manage custom roles
+description: Custom roles enable users to create fine-grained authorization in Temporal Cloud. This will give you precise control over who can do what within your account.


small nit. "create fine-grained authorization" sounds a little awkward because we are not "creating authorization" it doesn't create authorization itself but more granular way to manage permission.

Recommendation:
"enable users to define granular permissions in Temporal Cloud."

LutaoX · 2026-06-02T21:31:21Z

+Use Custom Roles if you want more fine-grained authentication than Temporal Cloud's predefined roles and permissions provide.
+
+Use Custom Roles if your access model enforces least-privilege access to grant users and service accounts only the operations they explicitly need, and no more.
+
+Using Custom Roles with [Service Accounts](/cloud/service-accounts) can make them more secure for automation purposes. 


Suggested change

Use Custom Roles if you want more fine-grained authentication than Temporal Cloud's predefined roles and permissions provide.

Use Custom Roles if your access model enforces least-privilege access to grant users and service accounts only the operations they explicitly need, and no more.

Using Custom Roles with [Service Accounts](/cloud/service-accounts) can make them more secure for automation purposes.

Use Custom Roles when you need more granular access control than the [predefined roles](https://docs.temporal.io/cloud/users#account-level-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.

LutaoX · 2026-06-02T22:38:01Z

+| **Resource Type** | **Scoping Behavior** | NOTE |
+| --- | --- | --- |
+| account | Account-level; no specific resource ID needed     |  |
+| projects (coming soon)  | [At the time of Custom Roles release] Scoped to default project <br />[Future] Scoped to specific project IDs, or `allow_all: true` for all projects.  | `default` project to start with because with introduction of projects, all namespaces will be moved to `default` project to start with   |


we can remove Projects

LutaoX · 2026-06-02T22:38:58Z

+- **Resource Types & Scoping Behavior**
+
+| **Resource Type** | **Scoping Behavior** | NOTE |
+| --- | --- | --- |
+| account | Account-level; no specific resource ID needed     |  |
+| projects (coming soon)  | [At the time of Custom Roles release] Scoped to default project <br />[Future] Scoped to specific project IDs, or `allow_all: true` for all projects.  | `default` project to start with because with introduction of projects, all namespaces will be moved to `default` project to start with   |
+| Namespaces | Scoped to specific Namespace IDs, or `allow_all: true` for all Namespaces    |  |
+| Nexus endpoints | Scoped to specific Nexus endpoint IDs, or `allow_all: true` for all Nexus endpoints |  |
+| connectivity rules | Scoped to specific connectivity rule IDs, or `allow_all: true` for all connectivity rules |  |


since we don't need Projects anymore. we probably don't need this table. The scoping behavior is the same across all other resources

LutaoX · 2026-06-02T22:39:08Z

+
+For a list of available actions, see [the list of Custom Role permissions](https://github.com/temporalio/saas-proto/blob/main/protogen/custom_role_permissions.json).
+    - Account-scoped actions (resource_type: "accounts")
+    - Project-scoped actions (resource_type: "projects")


LutaoX · 2026-06-03T15:45:25Z

+
+Either `allow_all: true` or `resource_ids` must be set, not both.
+
+For a list of available actions, see [the list of Custom Role permissions](https://github.com/temporalio/saas-proto/blob/main/protogen/custom_role_permissions.json).


This link is the internal json file Eng team produced so that doc and UI team can refer to for creating a user facing content.

We need a separate reference page created in public doc with this information that is 1) user friendly and 2) in sync with this internal json file so we don't need to manually keep the page updated

LutaoX · 2026-06-03T15:46:33Z

+The following example allows creating Namespaces in all projects.
+The action is `cloud.namespace.create`, the resource type is `projects`, and `allow_all` is set to true.
+
+```jsx
+  {
+    "actions": ["cloud.namespace.create"],
+    "resources": {
+      "resource_type": "projects",
+      "allow_all": true
+    }
+  }
+```
+


This example can be deleted

we can keep the two below example: one illustrating specific resource with ID, one illustrate mix and match to all resources.

Add documentation for Custom Roles feature

4d798f2

brianmacdonald-temporal requested a review from LutaoX March 13, 2026 19:10

vercel Bot deployed to Preview March 13, 2026 19:11 View deployment

LutaoX reviewed Mar 13, 2026

View reviewed changes

Comment thread docs/cloud/manage-access/custom-roles.mdx

captainbeardo reviewed Mar 13, 2026

View reviewed changes

Comment thread docs/cloud/manage-access/custom-roles.mdx Outdated

bechols reviewed Mar 13, 2026

View reviewed changes

LutaoX reviewed Mar 16, 2026

View reviewed changes

Comment thread docs/cloud/manage-access/custom-roles.mdx

sync-by-unito Bot assigned brianmacdonald-temporal Mar 24, 2026

Update docs/cloud/manage-access/custom-roles.mdx

dc03bae

Co-authored-by: Ben Echols <benjamin.echols@temporal.io>

vercel Bot deployed to Preview April 1, 2026 18:01 View deployment

Update docs/cloud/manage-access/custom-roles.mdx

2fad2fd

Co-authored-by: Ben Echols <benjamin.echols@temporal.io>

vercel Bot deployed to Preview April 1, 2026 18:05 View deployment

brianmacdonald-temporal added 2 commits April 1, 2026 14:37

Updates to Custom Roles documentation

11fe9a4

Merge branch 'custom-roles' of https://github.com/temporalio/document…

869f6ca

…ation into custom-roles

vercel Bot deployed to Preview April 1, 2026 18:48 View deployment

Merge branch 'main' into custom-roles

3c9288d

vercel Bot had a problem deploying to Preview April 1, 2026 18:59 Failure

Merge branch 'main' into custom-roles

9ce7dd0

vercel Bot had a problem deploying to Preview April 8, 2026 20:18 Failure

Removing duplicate file to fix bad link error

0bfb41f

vercel Bot had a problem deploying to Preview April 9, 2026 17:53 Failure

Merge branch 'main' into custom-roles

5a6a67e

vercel Bot had a problem deploying to Preview April 9, 2026 18:01 Failure

brianmacdonald-temporal added 2 commits April 17, 2026 12:45

feat(custom roles): updated Web UI

2fea29b

Merge branch 'main' into custom-roles

4550802

vercel Bot deployed to Preview April 17, 2026 16:49 View deployment

Adding admonition about additive permissions

b89e206

vercel Bot deployed to Preview April 17, 2026 17:22 View deployment

Merge branch 'main' into custom-roles

aeab167

vercel Bot had a problem deploying to Preview May 18, 2026 18:20 Failure

Merge branch 'main' into custom-roles

256dc2b

vercel Bot had a problem deploying to Preview May 18, 2026 18:25 Failure

Update users.mdx

64bbfd8

Fixing broken links

vercel Bot deployed to Preview May 18, 2026 19:32 View deployment

Merge branch 'main' into custom-roles

9b2b0c6

vercel Bot deployed to Preview May 21, 2026 19:30 View deployment

Adding API call content

91098b6

vercel Bot deployed to Preview May 29, 2026 20:26 View deployment

LutaoX marked this pull request as ready for review June 2, 2026 21:07

LutaoX requested a review from a team as a code owner June 2, 2026 21:07

LutaoX reviewed Jun 4, 2026

View reviewed changes


		For more information about the limits of Custom Roles, see [Custom Roles limits](/cloud/limits#custom-role-limits).

		## Defining Custom Roles

	scoped to applicable resources (namespaces or account objects) and assign them to any
	scoped to Temporal Cloud resources (e.g. [Account](https://docs.temporal.io/cloud/manage-access#temporal-cloud-accounts), [Namespace](https://docs.temporal.io/namespaces), [Nexus Endpoint](https://docs.temporal.io/nexus/endpoints), [Connectivity Rule](https://docs.temporal.io/cloud/connectivity#connectivity-rules) and assign them to any


		Temporal Cloud offers a set of predefined [account-level roles and Namespace-level permissions](https://docs.temporal.io/cloud/users#account-level-roles).
		These roles are sufficient for many Temporal use cases, but can't cover all combinations of least privilege, delegation, and automation-safe permissions often required in large enterprises.

-Use Custom Roles if you want more fine-grained authentication than Temporal Cloud's predefined roles and permissions provide.
-Use Custom Roles if your access model enforces least-privilege access to grant users and service accounts only the operations they explicitly need, and no more.
-Using Custom Roles with [Service Accounts](/cloud/service-accounts) can make them more secure for automation purposes.
+Use Custom Roles when you need more granular access control than the [predefined roles](https://docs.temporal.io/cloud/users#account-level-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.


		Either `allow_all: true` or `resource_ids` must be set, not both.

		For a list of available actions, see [the list of Custom Role permissions](https://github.com/temporalio/saas-proto/blob/main/protogen/custom_role_permissions.json).

Conversation

brianmacdonald-temporal commented Mar 13, 2026 • edited by sync-by-unito Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

Notes to reviewers

Uh oh!

vercel Bot commented Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📖 Docs PR preview links

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

brianmacdonald-temporal commented Mar 13, 2026 •

edited by sync-by-unito Bot

Loading

vercel Bot commented Mar 13, 2026 •

edited

Loading

github-actions Bot commented Mar 13, 2026 •

edited

Loading