Add documentation for Custom Roles feature

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

@@ -0,0 +1,139 @@
+---
+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.
+slug: /cloud/manage-access/custom-roles
+toc_max_heading_level: 4
+keywords:
+  - explanation
+  - feature
+  - manage access
+  - custom roles
+  - how to
+tags:
+  - Temporal Cloud
+  - custom roles
+  - user management
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+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.
+
+## 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 
+principal (user, group, service account). 
+
+## Why use Custom Roles?
+
+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. 
+
+## Custom Roles limits
+
+For more information about the limits of Custom Roles, see [Custom Roles limits](/cloud/limits#custom-role-limits).
+
+## Defining Custom Roles
+
+Custom Roles are made up of bundles of permission operations that map to Temporal Control Plane operations.
+You can scope a permission to all resources of a type, or to specific resources.
+
+For example, the following JSON code defines a global, read-only Namespace role called `NamespaceGlobalReadOnly`,
+to use for auditing and monitoring. 
+Users with this role will be able to retrieve information about any Namespace, but will not be able to modify them.
+The `grants` field is an array of the available permission operations, in this case `cloud.namespace.list` and `cloud.namespace.get`.
+The operations are limited to a `resourceType` of `Namespace`, and the scope is `all`.
+
+You can scope roles to:
+* All resources of a given type
+* Specific resources by explicit ID list
+
+```
+{
+  "name": "NamespaceGlobalReadOnly",
+  "description": "Read-only access to all namespaces for monitoring and compliance",
+  "grants": [
+    {
+      "operation": "cloud.namespace.list",
+      "resourceType": "Namespace",
+      "scope": { "all": true }
+    },
+    {
+      "operation": "cloud.namespace.get",
+      "resourceType": "Namespace",
+      "scope": { "all": true }
+    }
+  ]
+}
+```
+
+### Create Custom Roles from the Web UI
+
+<!-- TBD: The UI is subject to change -->
+
+To create a Custom Role from the Web UI, select Org 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.
+In the Permissions section, you'll assign the appropriate resources and its permissions.
+Select the Resource Type from the drop-down; your choices are Namespace and Account.
+
+If you select Namespace, search for the Namespace for which you want to add permissions, then click Add Resource.
+The Namespace you selected appears in the Permissions By Resource list.
+
+If you select Account, the permissions apply to the current account, so only the Add Resource button appears. 
+Click Add Resource, and the Account will be added to the Permissions By Resource list.
+
+Once the Namespace or Account appears in the Permissions By Resource list, you can toggle individual permissions
+on or off for that resource. 
+If you want to start with the permission set of one of the pre-defined Temporal roles, choose the role from 
+the Select Preset drop-down, and the appropriate permissions will be toggled for you.
+
+<!-- TBD: If we choose to add info about available permissions, we should add a link or list here. -->
+
+When you're done assiging permissions to resources, click Create Custom Role at the bottom of the page.
+
+### Create Custom Roles with the API
+
+<!-- Need more information here. -->
+
+### Create Custom Roles with Terraform
+
+<!-- Need more information here. -->
+
+## 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](/cloud/users#update-roles)
+for more inforamtion.
+
+## Available permissions
+
+Most of the Control Plane operations listed in the API references ([HTTP](https://saas-api.tmprl.cloud/docs/httpapi.html#description/introduction),
+[GRPC](https://saas-api.tmprl.cloud/docs/grpcapi/)) can be assigned to a Custom Role. 
+For the operations that are supported by Custom Roles, you will see the naming specification available next to each API call description.
+
+The following operations are not available to Custom Roles:
+
+- Creating an API key or a service account. These operations are part of the pre-defined roles (admin or above) and cannot be assigned to other less-privileged roles.
+- Operations that require additional role and permission validation, such as Create a Nexus Endpoint.
+- Separating or splitting operations that are part of UpdateNamespace.
+
+## Modifying a Custom Role
+
+<!-- Need more information here. -->
+
+## Deleting a Custom Role
+
+<!-- Need more information here. -->

docs/cloud/manage-access/index.mdx

@@ -52,22 +52,8 @@ Temporal Cloud offers the following principals for access control:
 - [**Users**](/cloud/users) - Manage individual user accounts and permissions
 - [**User Groups**](/cloud/user-groups) - Organize users into groups for simplified access management
 - [**Service Accounts**](/cloud/service-accounts) - Configure service accounts for automated access
-
-These principals can assume [account-level roles](/cloud/manage-access/roles-and-permissions#account-level-roles) and be
-granted [Namespace-level permissions](/cloud/manage-access/roles-and-permissions#namespace-level-permissions) to perform
-actions within the account and a Namespace, respectively.
-
-## Roles and permissions
-
-Temporal Cloud's RBAC model works in a hierarchical manner. Account-level roles grant permissions to perform actions
-within the account, and Namespace-level permissions grant permissions to perform actions within a Namespace. Refer to
-the [Roles and permissions](/cloud/manage-access/roles-and-permissions) page for more details.
-
-## Integration with identity providers
-
-Temporal Cloud supports SAML and SCIM for integration with your organization's identity provider (IDP).
-
-- [**SAML**](/cloud/saml) - Configure SAML-based SSO integration
+- [**Custom Roles**](/cloud/manage-access/custom-roles) - Define custom permissions for specific use cases
+- [**SAML**](/cloud/saml) - Configure SAML-based single sign-on integration
 - [**SCIM**](/cloud/scim) - Use your IDP to manage Temporal Cloud users and access via SCIM integration
 
 ## Troubleshoot account access issues