diff --git a/docs/cloud/get-started/users.mdx b/docs/cloud/get-started/users.mdx
deleted file mode 100644
index b0ab4a8b22..0000000000
--- a/docs/cloud/get-started/users.mdx
+++ /dev/null
@@ -1,218 +0,0 @@
----
-id: users
-title: Manage users
-sidebar_label: Manage users
-description:
- Manage user invitations, account-level roles, and Namespace-level permissions in Temporal Cloud. Invite users, update
- roles, and delete users seamlessly using the Temporal Web UI, tcld, or the Cloud Ops API.
-slug: /cloud/users
-toc_max_heading_level: 4
-keywords:
- - explanation
- - how-to
- - introduction
- - namespace
- - namespaces
- - temporal cloud
- - temporal cloud account
- - users
-tags:
- - Temporal Cloud
- - Namespaces
- - Users
----
-
-Users are one of the primary access principals in Temporal Cloud. Each user is assigned one
-[account-level role](/cloud/manage-access/roles-and-permissions#account-level-roles), and each role has a set of
-permissions. In addition to account-level roles, users can also be assigned
-[Namespace-level permissions](/cloud/manage-access/roles-and-permissions#namespace-level-permissions) for specific
-Namespaces. Each user can only perform an action if they have a role that grants them the necessary permissions.
-
-When you register for Temporal Cloud without joining an existing account, you are assigned the Account Owner role for a
-new account. You can then invite other users to join the account and assign them roles.
-
-## Invite users to your Temporal Cloud account {#invite-users}
-
-import InvitationContent from '@site/docs/cloud/get-started/user-invite.mdx';
-
-
-
-Global Admin roles cannot assign the Account Owner role or the Finance Admin role to new users they invite to the
-account.
-
-## Update a user's account-level role {#update-roles}
-
-With Global Admin or Account Owner privileges, you can update any user's account-level
-[role](/cloud/manage-access/roles-and-permissions#account-level-roles). The Account Owner role can only be granted by
-existing Account Owners.
-
-For security reasons, you cannot remove the Account Owner role from a user. Removing the Account Owner role must be made
-through Temporal Support. To remove the Account Owner role, you must submit a
-[support ticket](https://temporalsupport.zendesk.com/).
-
-
-
-
-
-1. In Temporal Web UI, select **Settings** in the left portion of the window.
-1. On the **Settings** page, select the user.
-1. On the user profile page, select **Edit User**.
-1. On the **Edit User** page in **Account Level Role**, select the role.
-1. Select **Save**.
-
-
-
-
-
-Use the [`tcld user set-account-role`](/cloud/tcld/user/#set-account-role) command. Specify the user by email or ID and
-the new role.
-
-Available account roles: `admin` | `developer` | `read`. The Account Owner and Finance Admin roles cannot be assigned
-through tcld; use the Web UI or Cloud Ops API to assign these roles.
-
-```command
-tcld user set-account-role --user-email --account-role
-```
-
-You can also identify the user by ID:
-
-```command
-tcld user set-account-role --user-id --account-role
-```
-
-
-
-
-
-Use the [UpdateUser](https://saas-api.tmprl.cloud/docs/httpapi.html#tag/users) endpoint to update a user's account-level
-role.
-
-```
-POST /cloud/users/{userId}
-```
-
-The request body includes a `spec` with the user's `access.account_access.role` field set to the desired role.
-
-Available roles: `ROLE_OWNER` | `ROLE_ADMIN` | `ROLE_DEVELOPER` | `ROLE_FINANCE_ADMIN` | `ROLE_READ`.
-
-
-
-
-
-## Update a user's Namespace-level permissions {#update-permissions}
-
-With Account Owner, Global Admin, or Namespace Admin privileges, you can update
-[Namespace-level permissions](/cloud/manage-access/roles-and-permissions#namespace-level-permissions) for users within
-Namespaces you administer. Account Owners and Global Admins have Namespace Admin permissions on all Namespaces
-automatically.
-
-
-
-
-
-**Update a user's permissions across multiple Namespaces:**
-
-1. In Temporal Web UI, select **Namespaces** in the left portion of the window.
-1. On the **Namespaces** page, select the Namespace.
-1. If necessary, scroll down to the list of permissions.
-1. On the user profile page in **Namespace permissions**, select the Namespace.
-1. On the Namespace page in **Account Level Role**, select the role.
-1. Select **Save**.
-
-**Update permissions for multiple users within a single Namespace:**
-
-1. In Temporal Web UI, select **Settings** in the left portion of the window.
-1. On the **Settings** page in the **Users** tab, select the user.
-1. On the user profile page, select **Edit User**.
-1. On the **Edit User** page in **Namespace permissions**, change the permissions for one or more Namespaces.
-1. Select **Save**.
-
-
-
-
-
-Use the [`tcld user set-namespace-permissions`](/cloud/tcld/user/#set-namespace-permissions) command. Specify the user
-by email or ID and one or more Namespace permissions.
-
-Each permission value must be in the format `namespace=permission-type`.
-
-Available Namespace permissions: `Admin` | `Write` | `Read`.
-
-```command
-tcld user set-namespace-permissions --user-email --namespace-permission =
-```
-
-You can set multiple Namespace permissions in a single request:
-
-```command
-tcld user set-namespace-permissions --user-email \
- --namespace-permission ns1=Admin \
- --namespace-permission ns2=Write
-```
-
-
-
-
-
-Use the [SetUserNamespaceAccess](https://saas-api.tmprl.cloud/docs/httpapi.html#tag/users) endpoint to set a user's
-permission for a specific Namespace.
-
-```
-POST /cloud/namespaces/{namespace}/users/{userId}/access
-```
-
-Set the `access.permission` field to the desired permission.
-
-Available permissions: `PERMISSION_ADMIN` | `PERMISSION_WRITE` | `PERMISSION_READ`.
-
-
-
-
-
-## Delete a user from your Temporal Cloud account {#delete-users}
-
-With Account Owner or Global Admin privileges, you can delete a user from your Temporal Cloud account.
-
-
-
-
-
-1. In Temporal Web UI, select **Settings** in the left portion of the window.
-1. On the **Settings** page, find the user and, on the right end of the row, select **Delete**.
-1. In the **Delete User** dialog, select **Delete**.
-
-You can also delete a user in two other ways in Web UI:
-
-- User profile page: Select the down arrow next to **Edit User** and then select **Delete**.
-- **Edit User** page: Select **Delete User**.
-
-
-
-
-
-Use the [`tcld user delete`](/cloud/tcld/user/#delete) command. Specify the user by email or ID.
-
-```command
-tcld user delete --user-email
-```
-
-You can also identify the user by ID:
-
-```command
-tcld user delete --user-id
-```
-
-
-
-
-
-Use the [DeleteUser](https://saas-api.tmprl.cloud/docs/httpapi.html#tag/users) endpoint to remove a user from your
-account.
-
-```
-DELETE /cloud/users/{userId}
-```
-
-
-
-
diff --git a/docs/cloud/manage-access/custom-roles.mdx b/docs/cloud/manage-access/custom-roles.mdx
new file mode 100644
index 0000000000..dd7eb7d7c2
--- /dev/null
+++ b/docs/cloud/manage-access/custom-roles.mdx
@@ -0,0 +1,278 @@
+---
+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
+
+:::warning Custom Roles are additive only
+
+Custom Roles define a set of granular permissions and assign them alongside a 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.
+
+:::
+
+## 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.
+
+## 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.
+
+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.
+- Project: Permissions scoped to the selected Project, listed by type. You must have at least one Project enabled before you can assign Project permissions to a Custom Role.
+- 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.
+
+TODO: Resolve how we're going to talk about Projects for this release; get clarity on Connectivity Rules.
+
+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.
+
+
+
+
+Use the [`CreateCustomRoleRequest` API call](https://buf.build/temporalio/cloud-api/docs/main:temporal.api.cloud.cloudservice.v1#temporal.api.cloud.cloudservice.v1.CreateCustomRoleRequest) to create a Custom Role.
+The structure of the `CreateCustomRoleRequest` is as follows:
+
+```
+{
+ "spec": {
+ "name": "my-role-name",
+ "description": "Optional description",
+ "permissions": [
+ {
+ "actions": ["cloud.namespace.create"],
+ "resources": {
+ "resource_type": "projects",
+ "allow_all": true
+ }
+ }
+ ]
+ }
+}
+```
+
+This example creates a Custom Role with the defined `spec`.
+The example shown here creates a role named `my-role-name` and grants the ability to create projects in all Namespaces.
+The request returns a `RoleID`.
+
+The following constraints apply to the request:
+
+- **Name constraints:**
+ - A name is required, with a max of 64 characters
+ - The following characters are allowed: letters (a-z, A-Z), numbers (0-9), hyphens (-), underscores (_)
+ - Names are not unique per account, meaning two different roles can share the same name
+- **Description constraints:**
+ - A description is optional, with a max of 256 characters
+- **Permissions constraints:**
+ - At least one permission is required
+ - You can assign up to 25 permissions per role (account default, may vary)
+
+**Permission Structure**
+
+Each permission has two parts: actions and resources.
+
+- **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
[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 | |
+
+Resource IDs must exist in your account. Specifying an unknown resource ID will return an error.
+
+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).
+ - Account-scoped actions (resource_type: "accounts")
+ - Project-scoped actions (resource_type: "projects")
+ - Namespace-scoped actions (resource_type: "namespaces")
+ - Nexus endpoint-scoped actions (resource_type: "nexus_endpoints")
+ - Connectivity rule-scoped actions (resource_type: "connectivity_rules")
+
+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
+ }
+ }
+```
+
+The following example allows read access to specific Namespaces.
+The action is `cloud.namespace.get`, the resource type is `namespaces`, and the list of resource IDs is specified.
+
+```jsx
+{
+ "actions": ["cloud.namespace.get"],
+ "resources": {
+ "resource_type": "namespaces",
+ "resource_ids": ["my-namespace.account-id"]
+ }
+ }
+```
+
+The following example assigns multiple permissions to one Role.
+The permissions are assigned in an array, with the action `cloud.namespace.get` granted for all Namespaces, and `cloud.user.list` granted for all accounts.
+
+```jsx
+ {
+ "spec": {
+ "name": "ns-reader-user-lister",
+ "description": "Can read namespaces and list users",
+ "permissions": [
+ {
+ "actions": ["cloud.namespace.get"],
+ "resources": { "resource_type": "namespaces", "allow_all": true }
+ },
+ {
+ "actions": ["cloud.user.list"],
+ "resources": { "resource_type": "accounts", "allow_all": true }
+ }
+ ]
+ }
+ }
+```
+
+For more information about the `CustomRole` and `CustomRoleSpec` definitions, see the [Schema Registry](https://buf.build/temporalio/cloud-api/docs/f22f274c493a4c9b931514dca6ffcf44:temporal.api.cloud.identity.v1#temporal.api.cloud.identity.v1.CustomRole).
+
+
+
+
+## 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.
+
+## 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.
+
+
+
+
+Use the [`UpdateCustomRoleRequest` API call](https://buf.build/temporalio/cloud-api/docs/main:temporal.api.cloud.cloudservice.v1#temporal.api.cloud.cloudservice.v1.UpdateCustomRoleRequest) to modify the 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.
+
+
+
+
+Use the [`UpdateCustomRoleRequest` API call](https://buf.build/temporalio/cloud-api/docs/main:temporal.api.cloud.cloudservice.v1#temporal.api.cloud.cloudservice.v1.DeleteCustomRoleRequest) to delete the Custom Role:
+
+
+
diff --git a/docs/cloud/manage-access/index.mdx b/docs/cloud/manage-access/index.mdx
index ef58f918cd..5286fd0205 100644
--- a/docs/cloud/manage-access/index.mdx
+++ b/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
diff --git a/docs/cloud/manage-access/saml.mdx b/docs/cloud/manage-access/saml.mdx
new file mode 100644
index 0000000000..38bf25a093
--- /dev/null
+++ b/docs/cloud/manage-access/saml.mdx
@@ -0,0 +1,176 @@
+---
+id: saml
+title: SAML authentication
+sidebar_label: SAML authentication
+description:
+ Integrate SAML 2.0 with your Temporal Cloud account for secure user authentication. Connect via Microsoft Entra ID or
+ Okta and ensure seamless SSO. Charges apply.
+slug: /cloud/saml
+toc_max_heading_level: 4
+keywords:
+ - how-to
+ - introduction
+ - security
+ - temporal cloud
+tags:
+ - Security
+ - Temporal Cloud
+ - Users
+---
+
+To authenticate the users of your Temporal Cloud account, you can connect an identity provider (IdP) to your account by
+using Security Assertion Markup Language (SAML) 2.0.
+
+:::info
+
+SAML is a paid feature. See the [pricing page](/cloud/pricing) for details.
+
+:::
+
+## Integrate SAML with your Temporal Cloud account
+
+1. Locate your [Temporal Cloud Account Id](/cloud/namespaces#temporal-cloud-account-id). Your Account Id can be viewed
+ and copied from the Temporal Cloud user profile dropdown menu in the top right corner. Alternatively, find your
+ [Namespace Id](/cloud/namespaces#temporal-cloud-namespace-id). The Account Id is the five or six characters following
+ the period (.), such as `f45a2`. You will need the Account Id to construct your callback URL and your entity
+ identifier.
+1. Configure SAML with your IdP by following one of these sets of instructions:
+ - [Microsoft Entra ID](#configure-saml-with-azure-ad)
+ - [Okta](#configure-saml-with-okta)
+1. [Share your connection information with us and test your connection.](#finish-saml-configuration)
+
+## How to configure SAML with Microsoft Entra ID {#configure-saml-with-azure-ad}
+
+If you want to use the general Microsoft login mechanism, you don't need to set up SAML with Entra ID. Just select
+**Continue with Microsoft** on the Temporal Cloud sign-in page.
+
+To use Entra ID as your SAML IdP, create a Microsoft Entra ID Enterprise application.
+
+1. Sign in to the [Microsoft Entra ID](https://portal.azure.com/).
+1. On the home page, under **Manage Microsoft Entra ID**, select **View**.
+1. On the **Overview** page near the top, select **Add > Enterprise application**.
+1. On the **Browse Microsoft Entra ID Gallery** page near the top, select **Create your own application**.
+1. In the **Create your own application** pane, provide a name for your application (such as `temporal-cloud`) and
+ select **Integrate any other application you don't find in the gallery**.
+1. Select **Save**.
+1. In the **Getting Started** section, select **2. Set up single sign on**.
+1. On the **Single sign-on** page, select **SAML**.
+1. In the **Basic SAML Configuration** section of the **SAML-based Sign-on** page, select **Edit**.
+1. In **Identifier (Entity ID)**, enter the following entity identifier, including your Account Id where indicated:
+
+ ```bash
+ urn:auth0:prod-tmprl:ACCOUNT_ID-saml
+ ```
+
+ A correctly formed entity identifier looks like this:
+
+ ```bash
+ urn:auth0:prod-tmprl:f45a2-saml
+ ```
+
+1. In **Reply URL (Assertion Consumer Service URL)**, enter the following callback URL, including your Account Id where
+ indicated:
+
+ ```bash
+ https://login.tmprl.cloud/login/callback?connection=ACCOUNT_ID-saml
+ ```
+
+ A correctly formed callback URL looks like this:
+
+ ```bash
+ https://login.tmprl.cloud/login/callback?connection=f45a2-saml
+ ```
+
+1. In **Sign on URL**, enter the following login url, including your Account Id where indicated:
+
+ ```bash
+ https://cloud.temporal.io/login/saml?connection=ACCOUNT_ID-saml
+ ```
+
+ A correctly formed login URL looks like this:
+
+ ```bash
+ https://cloud.temporal.io/login/saml?connection=f45a2-saml
+ ```
+
+1. You can leave the other fields blank. Near the top of the pane, select **Save**.
+1. In the **Attributes & Claims** section, select **Edit**. Configure the following settings. Under **Required claim**:
+
+ - Set **Unique User Identifier (NameID)** to `user.userprincipalname`
+ - Set the **NameID format** to `emailAddress`
+
+ These are the default settings for Microsoft Entra ID. Then under **Additional claims**, ensure **Email** and
+ **Name** are present.
+
+1. Collect information that you need to send to us:
+ - In the **SAML Certificates** section of the **SAML-based Sign-on** page, select the download link for **Certificate
+ (Base64)**.
+ - In the **Set up _APPLICATION_NAME_** section of the **SAML-based Sign-on** page, copy the value of **Login URL**.
+
+To finish setting up Microsoft Entra ID as your SAML IdP, see [Finish SAML configuration](#finish-saml-configuration).
+
+## How to configure SAML with Okta {#configure-saml-with-okta}
+
+To use Okta as your SAML IdP, configure a new Okta application integration.
+
+1. Sign in to the [Okta Admin Console](https://www.okta.com/login/).
+1. In the left navigation pane, select **Applications > Applications**.
+1. On the **Applications** page, select **Create App Integration**.
+1. In the **Create a new app integration** dialog, select **SAML 2.0** and then select **Next**.
+1. On the **Create SAML Integration** page in the **General Settings** section, provide a name for your application
+ (such as `temporal-cloud`) and then select **Next**.
+1. In the **Configure SAML** section in **Single sign on URL**, enter the following callback URL, including your Account
+ Id where indicated:
+
+ ```bash
+ https://login.tmprl.cloud/login/callback?connection=ACCOUNT_ID-saml
+ ```
+
+ A correctly formed callback URL looks like this:
+
+ ```bash
+ https://login.tmprl.cloud/login/callback?connection=f45a2-saml
+ ```
+
+1. In **Audience URI (SP Entity ID)**, enter the following entity identifier, including your Account Id where indicated:
+
+ ```bash
+ urn:auth0:prod-tmprl:ACCOUNT_ID-saml
+ ```
+
+ A correctly formed entity identifier looks like this:
+
+ ```bash
+ urn:auth0:prod-tmprl:f45a2-saml
+ ```
+
+1. We require the user's full email address when connecting to Temporal.
+ - In **Name ID format**, select `EmailAddress`.
+ - In **Attribute Statements**, set **email** and **name**.
+1. Select **Next**.
+1. In the **Feedback** section, select **Finish**.
+1. On the **Applications** page, select the name of the application integration you just created.
+1. On the application integration page, select the **Sign On** tab.
+1. Under **SAML Setup**, select **View SAML setup instructions**.
+1. Collect information that you need to send to us:
+ - Copy the IdP settings.
+ - Download the active certificate.
+
+To finish setting up Okta as your SAML IdP, see the next section,
+[Finish SAML configuration](#finish-saml-configuration).
+
+## How to finish your SAML configuration {#finish-saml-configuration}
+
+After you configure SAML with your IdP, we can finish the configuration on our side.
+[Create a support ticket](/cloud/support#support-ticket) that includes the following information:
+
+- The sign-in URL from your application
+- The X.509 SAML sign-in certificate in PEM format
+- One or more IdP domains to map to the SAML connection
+
+Generally, the provided IdP domain is the same as the domain for your email address. You can provide multiple IdP
+domains.
+
+When you receive confirmation from us that we have finished configuration, log in to Temporal Cloud. This time, though,
+enter your email address in **Enterprise identity** and select **Continue**. Do not select **Continue with Google** or
+**Continue with Microsoft**. You will be redirected to the authentication page of your IdP.
diff --git a/docs/cloud/manage-access/scim.mdx b/docs/cloud/manage-access/scim.mdx
new file mode 100644
index 0000000000..4b8c473a38
--- /dev/null
+++ b/docs/cloud/manage-access/scim.mdx
@@ -0,0 +1,81 @@
+---
+id: scim
+title: SCIM user management
+sidebar_label: SCIM user management
+description: Link your IdP with your Temporal Cloud account to securely automate user and group management.
+slug: /cloud/scim
+toc_max_heading_level: 3
+keywords:
+ - authentication
+ - authorization
+ - how-to
+ - introduction
+ - lifecycle
+ - security
+ - temporal cloud
+ - user management
+tags:
+ - Security
+ - Temporal Cloud
+ - User groups
+ - Users
+---
+
+[SCIM](https://scim.cloud/) lets you integrate your identity provider (IdP) with Temporal Cloud to automate user provisioning and access. Once SCIM is configured, changes in your IdP are automatically reflected in Temporal Cloud, including:
+
+- User creation / onboarding
+- User deletion / offboarding
+- User membership in groups
+
+You can map SCIM groups to Temporal Cloud [roles and permissions](/cloud/users#account-level-roles-and-namespace-level-permissions), so users automatically get the Temporal Cloud access they need based on the groups they belong to.
+
+:::info
+
+SCIM is a paid feature. See the [pricing page](/cloud/pricing) for details.
+
+:::
+
+## Supported IdP Vendors
+
+Supported upstream IdP vendors include:
+* [Okta](#configure-scim-with-okta)
+* Microsoft Entra ID (Azure AD)
+* Google Workspace
+* OneLogin
+* CyberArk
+* JumpCloud
+* PingFederate
+* Any SCIM 2.0-compliant provider
+
+## Preparing for SCIM
+
+Before starting your work with SCIM, you'll need to complete this checklist:
+
+1. Configure [SAML](/cloud/saml) SSO.
+1. Identify your organization's **IdP administrator**, who is responsible for configuring and managing your SCIM integration.
+ Specify their contact details when you reach out to support in the next stage of this process.
+
+After completing these steps, you're ready to submit your [support ticket](/cloud/support#support-ticket) to enable SCIM.
+
+:::tip Adding and removing users
+
+When SCIM is enabled for user management, you can still add and remove users outside of SCIM using the Temporal Cloud interface, until you disable user lifecycle management.
+You can always change a user's or group's Account Role from the Temporal Cloud interface.
+
+:::
+
+## Onboarding with SCIM and Okta {#configure-scim-with-okta}
+
+1. Temporal Support enables the SCIM integration on your account.
+ Enabling integration automatically emails a configuration link to your Okta administrator.
+ This authorizes them to set up the integration.
+1. Your Okta administrator opens the supplied link.
+ The link leads to step-by-step instructions for configuring the integration.
+1. Once configured in Okta, Temporal Cloud will begin to receive SCIM messages and automatically onboard and offboard the users and groups configured in Okta.
+
+Some points to note:
+
+- User and group change events are applied within 10 minutes of them being made in Okta.
+- User lifecycle management with SCIM also allows user roles to be derived from group membership.
+- Once a group has been synced in Temporal Cloud, you can use `tcld` to assign roles to the group.
+ For instructions, see the [User Group Management](https://github.com/temporalio/tcld?tab=readme-ov-file#user-group-management) page.
diff --git a/docs/cloud/manage-access/service-accounts.mdx b/docs/cloud/manage-access/service-accounts.mdx
new file mode 100644
index 0000000000..25330ea508
--- /dev/null
+++ b/docs/cloud/manage-access/service-accounts.mdx
@@ -0,0 +1,239 @@
+---
+id: service-accounts
+title: Manage service accounts
+sidebar_label: Manage service accounts
+description: Temporal Cloud introduces Service Accounts for machine authentication, enabling non-human identities to interact with Temporal Cloud. Manage Service Accounts via Cloud UI or CLI for secure, automated operations.
+slug: /cloud/service-accounts
+toc_max_heading_level: 4
+keywords:
+ - explanation
+ - feature
+ - get started
+ - machine authentication
+ - how to
+tags:
+ - Temporal Cloud
+ - API Keys
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+Temporal Cloud provides Account Owner and Global Admin [roles](/cloud/users#account-level-roles) with the option to create machine identities named Service Accounts.
+
+Service Accounts are a type of identity in Temporal Cloud.
+Temporal Cloud supports User identities as a representation of a human user who uses Temporal Cloud.
+Service Accounts afford Temporal Cloud Account Owner and Global Admin [roles](/cloud/users#account-level-roles) the ability to create an identity for machine authentication, an identity not associated with a human user.
+
+With the addition of Service Accounts, Temporal Cloud now supports 2 identity types:
+
+- Users (tied to a human, identified by email address or ID)
+- Service Accounts (not tied to a human, email address optional, identified by name or ID)
+
+Service Accounts use API Keys as the authentication mechanism to connect to Temporal Cloud.
+You should use Service Accounts to represent a non-human identity when authenticating to Temporal Cloud for operations automation or the Temporal SDKs and the Temporal CLI for Workflow Execution and management.
+
+:::tip
+
+Namespace Admins can now manage and create [Namespace-scoped Service Accounts](/cloud/service-accounts#scoped), regardless of their Account Role.
+
+:::
+
+## Manage Service Accounts
+
+Account Owner and Global Admin [roles](/cloud/users#account-level-roles) can manage Service Accounts by creating, viewing, updating, deleting Service Accounts using the following tools:
+
+- Temporal Cloud UI
+- Temporal Cloud CLI (tcld)
+ - Use `tcld service-account --help` for a list of all service-account commands
+
+Account Owner and Global Admin [roles](/cloud/users#account-level-roles) also have the ability to manage API Keys for Service Accounts.
+
+### Prerequisites
+
+- A Cloud user account with Account Owner or Global Admin [role](/cloud/users#account-level-roles) permissions
+- Access to the Temporal Cloud UI or Temporal Cloud CLI (tcld)
+- Enable access to API Keys for your Account
+- To manage Service Accounts using the Temporal Cloud CLI (tcld), upgrade to the latest version of tcld (v0.18.0 or higher) using `brew upgrade tcld`.
+ - If using a version of tcld less than v0.31.0, enable Service Account commands with `tcld feature toggle-service-account`.
+
+### Create a Service Account
+
+Create a Service Account using the Temporal Cloud UI or tcld.
+While User identities are invited to Temporal Cloud, Service Accounts are created in Temporal Cloud.
+
+
+
+
+1. Go to [Settings → Identities](https://cloud.temporal.io/settings/identities)
+2. Click the `Create Service Account` button located near the top of the `Identities` page
+3. Provide the following information:
+ - **Name** (required)
+ - **Description** (optional)
+ - **Account Level Role** (required)
+ - **Namespace Permissions** (optional)
+ - Use this section of the Create Service Account page to grant the Service Account access to individual Namespaces
+4. Click `Create Service Account` at the bottom of the page
+ - A status message is displayed at the bottom right corner of the screen and on the next screen
+ - You will be prompted to create an API Key for the Service Account (optional)
+5. (Optional) Create API Key
+ - It is recommended to create an API Key for the Service Account right after you create the Service Account, though you can create/manage API Keys for Service Accounts at any time
+ - See the API Key [documentation](/cloud/api-keys) for more information on creating and managing API Keys
+
+
+
+
+To create a Service Account using tcld, use the `tcld service-account create` command:
+
+```
+tcld service-account create -n "sa_test" -d "this is a test SA" --ar "Read"
+```
+
+This example creates a Service Account with the name `"sa_test"`, description `"this is a test SA"`, and a `Read` Account Role.
+
+Creating a Service Account requires the following attributes: `name` and `account-role` (as above).
+You can also provide the Namespace Permissions for the Service Account using the `—-np` flag.
+Creating a Service Account returns the `ServiceAccountId` which is used to retrieve, update, or delete a Service Account.
+
+
+
+
+### View Service Accounts
+
+View a single or all Service Account(s) using the Temporal Cloud UI or tcld.
+
+
+
+
+Service Accounts are listed on the `Identities` section of the `Settings` page, along with Users.
+To locate a Service Account:
+
+1. Go to [Settings → Identities](https://cloud.temporal.io/settings/identities)
+2. Select the `Service Accounts` filter
+
+
+
+
+To view all Service Accounts in your account using tcld, use the `tcld service-account list` command:
+
+```
+tcld service-account list
+```
+
+
+
+
+### Delete a Service Account
+
+Delete a Service Account using the Temporal Cloud UI or tcld. When you delete a Service Account, all associated API keys are automatically deleted as well.
+Therefore, you don't need to manually remove API keys after deleting a Service Account.
+
+
+
+
+1. Go to [Settings → Identities](https://cloud.temporal.io/settings/identities)
+2. Find the relevant Service Account
+3. Select the vertical ellipsis menu in the Service Account row
+4. Select `Delete`
+5. Confirm the delete action when prompted
+
+
+
+
+To delete a Service Account using tcld, use the `tcld service-account delete` command:
+
+```
+tcld service-account delete --service-account-id "e9d87418221548"
+```
+
+Use the tcld Service Account list command to validate the Service Account has been removed from the account.
+The Service Account is deleted when it is no longer visible in the output of the list command.
+
+
+
+
+### Update a Service Account {#update}
+
+Update a Service Account's description using the Temporal Cloud UI or tcld.
+
+
+
+
+1. Go to [Settings → Identities](https://cloud.temporal.io/settings/identities)
+2. Find the relevant Service Account
+3. Select the vertical ellipsis menu in the Service Account row
+4. Select `Edit`
+5. Make changes to the Service Account
+ - You can change the Service Account's name, description, Account Level Role, and Namespace Permissions
+6. Click the `Save` button located in the bottom left of the screen
+ - A status message is displayed at the bottom right corner of the screen
+
+
+
+
+Three different commands exist to help users update a Service Account using tcld:
+
+- `tcld service-account update`: to update a Service Account's name or description field
+- `tcld service-account set-account-role`: to update a Service Account's Account Role
+- `tcld service-account set-namespace-permissions`: to update a Service Account's Namespace Permissions
+
+Example:
+
+```
+tcld service-account update --id "2f68507677904e09b9bcdbf93380bb95" -d "new description"
+```
+
+
+
+
+
+## Namespace-scoped Service Accounts {#scoped}
+
+There is a special type of Service Account, called a Namespace-scoped Service Account, which shares the
+same functionality as the Service Accounts above, but is limited (or scoped) to a single namespace.
+
+In particular, a Namespace-scoped Service Account must _always_ have:
+
+- A `Read` Account Role
+- A single Namespace Permission
+
+Note that a Namespace-scoped Service Account cannot be reassigned to a different Namespace after creation, but its Namespace permission can be modified (e.g. from `Read` to `Write`).
+
+Namespace-scoped Service Accounts are useful in situations when you need to restrict a client's access to a single Namespace.
+
+You can retrieve, update, and delete a Namespace-scoped Service Account using the same process and commands as above, but creation is slightly different.
+
+### Permissions
+Unlike regular Service Accounts, which require a Global Admin or Account Owner role, Namespace-scoped Service Accounts can be created and managed by Namespace Admins.
+For example, an Account Developer with Namespace Admin for `test_ns` can create a Service Account scoped to `test_ns`.
+
+Global Admins and Account Owners can also create Namespace-scoped Service Accounts, as they implicitly have Namespace Admin rights for all Namespaces.
+
+### Create a Namespace-scoped Service Account
+
+As with regular Service Accounts, Namespace-scoped Service Accounts can be created using Temporal Cloud UI or tcld.
+
+#### Using the Cloud UI {#scoped-ui}
+
+Currently, creating a Namespace-scoped Service Account from the Temporal Cloud UI happens on an individual [Namespace](/cloud/namespaces#manage-namespaces) page.
+If the current Namespace has API key authentication enabled, then there will be a `Generate API Key` button as a banner on the top of the Namespace page or in the `Authentication` section.
+
+By clicking on the `Generate API Key` button, a Namespace-scoped Service Account will be automatically created for the given Namespace (if one does not already exist) and an associated API key will be displayed. This key will have the maximum expiration time, which is 2 years.
+
+The resulting Namespace-scoped Service Account will be named `-service-account` and will have an `Admin` Namespace permission by default.
+
+#### Using tcld
+
+To create a Namespace-scoped Service Account with tcld, use the `tcld service-account create-scoped` command:
+
+```
+tcld service-account create-scoped -n "test-scoped-sa" --np "test-ns=Admin"
+```
+
+This example creates a Namespace-scoped Service Account for the Namespace `test-ns`, named `test-scoped-sa`, with `Admin` Namespace Permission.
+Note that the Account Role is omitted, since Namespace-scoped Service Accounts always have a `Read` Account Role.
+
+### Lifecycle
+
+When a Namespace is deleted, all associated Namespace-scoped Service Accounts and their associated API keys are automatically deleted as well.
+Therefore, you do not need to manually remove Namespace-scoped Service Accounts and their API keys after deleting a Namespace.
diff --git a/docs/cloud/manage-access/user-groups.mdx b/docs/cloud/manage-access/user-groups.mdx
new file mode 100644
index 0000000000..b76b618a99
--- /dev/null
+++ b/docs/cloud/manage-access/user-groups.mdx
@@ -0,0 +1,175 @@
+---
+id: user-groups
+title: Manage user groups
+sidebar_label: Manage user groups
+description: Learn how to manage user groups, members, and roles
+slug: /cloud/user-groups
+toc_max_heading_level: 4
+keywords:
+ - explanation
+ - how-to
+ - temporal cloud
+ - temporal cloud account
+ - user groups
+tags:
+ - Users
+ - User groups
+ - Security
+ - Temporal Cloud
+---
+
+## What are user groups?
+
+User groups can be used to help manage sets of users that should have the same
+access. Instead of separately assigning the same role to individual users, a user group can be
+created, assigned the desired roles, and then users added to the user group. This
+eases the toil of managing individual user permissions and can simplify access management. When
+a new role is needed, it can be added to the group once and all users' access will reflect the
+new role.
+
+User groups can be assigned both [account-level roles](/cloud/users#account-level-roles) and [namespace-level permissions](/cloud/users#namespace-level-permissions).
+
+One user can be assigned to many groups. In the event that a user's group memberships have multiple roles for the same resource, the user will have an effective role of the most permissive of the permissions. For example if `Group A` grants a read-only role to a namespace, but `Group B` grants a write role to a namespace then a user that belongs to both `Group A` and `Group B` would have the write role to the namespace.
+
+[Service accounts](/cloud/service-accounts) cannot be assigned to user groups.
+
+Only users with the Account Owner or Global Admin account-level [role](/cloud/users#account-level-roles) can manage user groups.
+
+## How SCIM groups work with user groups {#scim-groups}
+
+[SCIM groups](/cloud/scim) work similarly to user groups with respect to role assignment. Unlike a user group, the lifecycle of a SCIM group is fully managed by the SCIM integration which means:
+
+1. SCIM groups cannot be created except through the SCIM integration
+1. SCIM groups cannot be deleted except through the SCIM integration
+1. SCIM group membership is managed through the SCIM integration
+
+User groups and SCIM groups can be used simultaneously in a single Temporal Cloud account. One user may belong to multiple SCIM groups and to multiple user groups.
+
+Using user group and SCIM groups together can be useful when the groups defined in the identity provider (IDP) don't map cleanly to the access you need to grant in Temporal Cloud. Instead of having to update the IDP (which is often sensitive and time-consuming), you can use Temporal Cloud user groups to manage access.
+
+:::info
+
+All user group administration requires an Account Owner or Global Admin account-level [role](/cloud/users#account-level-roles).
+
+:::
+
+## How to create a user group in your Temporal Cloud account {#create-group}
+
+User group names must be 3-64 characters long and can only contain lowercase letters, numbers, hyphens, and underscores.
+
+
+
+
+
+1. Navigate to the [identities page](https://cloud.temporal.io/settings/identities)
+1. Click the Create Group button
+1. Name the group
+1. Assign an account-level role to the group (you can assign namespace-level permissions after the group is created)
+1. Click Save
+
+
+
+
+See the [`tcld` user-group create](/cloud/tcld/user-group/#create) command reference for details.
+
+
+
+See the [Terraform provider documentation](https://registry.terraform.io/providers/temporalio/temporalcloud/latest/docs/resources/group) for details.
+
+
+
+
+## How to assign roles to a user group {#assign-group-roles}
+
+
+
+
+To edit the account role of a group:
+ 1. Navigate to the [identities page](https://cloud.temporal.io/settings/identities)
+ 1. Find the group to edit (You can filter the list of identities to only show groups to find the relevant group by clicking the Groups tab on the table)
+ 1. Click Edit Group
+ 1. Click the Account Role dropdown
+ 1. Select a new account role
+ 1. Click Save
+
+To add namespace permissions to a group:
+ 1. Navigate to the [identities page](https://cloud.temporal.io/settings/identities)
+ 1. Find the group to edit (You can filter the list of identities to only show groups to find the relevant group by clicking the Groups tab on the table)
+ 1. Click Edit Group
+ 1. Click Add Namespaces
+ 1. Under Grant Access to a Namespace, search for the namespace you’d like to add permissions for
+ 1. Select the namespace
+ 1. Click the pencil to edit the permissions for the selected namespace
+ 1. Click Save
+
+To edit or remove namespace permissions from a group:
+ 1. Click Edit Group
+ 1. Click the pencil on a permission to edit it, or the trash can to delete it
+ 1. Click Save
+
+
+
+
+See the [`tcld` user-group set-access](/cloud/tcld/user-group/#set-access) command reference for details.
+
+
+
+See the [Terraform provider documentation](https://registry.terraform.io/providers/temporalio/temporalcloud/latest/docs/resources/group) for details.
+
+
+
+
+## How to manage users in a group {#assign-group-members}
+
+
+
+
+To add users to the group:
+ 1. Navigate to the [identities page](https://cloud.temporal.io/settings/identities)
+ 1. Find the group to edit (You can filter the list of identities to only show groups to find the relevant group by clicking the Groups tab on the table)
+ 1. Click Edit Group
+ 1. Under Members, search for the user you’d like to add
+ 1. Select the user
+ 1. Click Save
+To remove a user from the group:
+ 1. Click Edit Group
+ 1. Under Members, click the X next to the user you’d like to remove
+ 1. Click Save
+
+
+
+
+See the [`tcld` user-group add-users](/cloud/tcld/user-group/#add-users) and the [`tcld` user-group remove-users](/cloud/tcld/user-group/#remove-users) command reference for details.
+
+
+
+See the [Terraform provider documentation](https://registry.terraform.io/providers/temporalio/temporalcloud/latest/docs/resources/group) for details.
+
+
+
+
+## Delete a user group
+
+
+
+
+ 1. Navigate to the [identities page](https://cloud.temporal.io/settings/identities)
+ 1. Find the group to edit (You can filter the list of identities to only show groups to find the relevant group by clicking the Groups tab on the table)
+ 1. Click the dropdown next to the edit button
+ 1. Click Delete
+ 1. Confirm by clicking Delete
+
+
+
+
+See the [`tcld` user-group delete](/cloud/tcld/user-group/#delete) command reference for details.
+
+
+
+See the [Terraform provider documentation](https://registry.terraform.io/providers/temporalio/temporalcloud/latest/docs/resources/group) for details.
+
+
+
+
+
+
diff --git a/docs/cloud/manage-access/users.mdx b/docs/cloud/manage-access/users.mdx
new file mode 100644
index 0000000000..887aa20639
--- /dev/null
+++ b/docs/cloud/manage-access/users.mdx
@@ -0,0 +1,393 @@
+---
+id: users
+title: Manage users
+sidebar_label: Manage users
+description: Learn how to manage user invitations, account-level roles, and Namespace-level permissions in Temporal Cloud. Invite users, update roles, and delete users seamlessly using the Temporal Web UI, tcld, or the Cloud Ops API.
+slug: /cloud/users
+toc_max_heading_level: 4
+keywords:
+ - explanation
+ - how-to
+ - introduction
+ - namespace
+ - namespaces
+ - temporal cloud
+ - temporal cloud account
+ - users
+tags:
+ - Temporal Cloud
+ - Namespaces
+ - Users
+---
+
+- [How to invite users to your Temporal Cloud account](#invite-users)
+- [What are the account-level roles?](#account-level-roles)
+- [What are the Namespace-level permissions?](#namespace-level-permissions)
+- [How to update an account-level Role in Temporal Cloud](#update-roles)
+- [How to update Namespace-level permissions in Temporal Cloud](#update-permissions)
+- [How to delete a user from your Temporal Cloud account](#delete-users)
+- [How to troubleshoot account access issues](#troubleshoot-access)
+
+## How to invite users to your Temporal Cloud account {#invite-users}
+
+import InvitationContent from '@site/docs/cloud/get-started/user-invite.mdx'
+
+
+
+## What are the account-level roles for users in Temporal Cloud? {#account-level-roles}
+
+When an Account Owner or Global Admin invites a user to join an account, they select one of the following roles for that user:
+
+- **Global Admin**
+ - Has full administrative permissions across the account, including users and usage
+ - Can create and manage [Namespaces](/namespaces) and [Nexus Endpoints](/nexus/endpoints)
+ - Has Namespace Admin [permissions](#namespace-level-permissions) on all Namespaces in the account.
+ This permission cannot be revoked
+- **Developer**
+ - Can create Namespaces
+ - Is granted [Namespace Admin](/cloud/users#namespace-level-permissions) permission for each Namespace they create.
+ This permission can be revoked
+ - Can create and manage Nexus Endpoints where they are a [Namespace Admin](/cloud/users#namespace-level-permissions) on the Endpoint's target Namespace
+- **Read-Only**
+ - Can read information
+ - Can be granted Namespace [permissions](#namespace-level-permissions), for example to read or write Workflow state in a given Namespace
+ - Can view all Nexus Endpoints in the account, which have separate [runtime access controls](/nexus/security#runtime-access-controls)
+
+In addition, there are two roles that the Global Admin cannot assign:
+
+- **Account Owner**
+ - Has full administrative permissions across the account, including users, usage and [billing](/cloud/billing-and-usage)
+ - Can create and manage Namespaces and Nexus Endpoints
+ - Has Namespace Admin [permissions](#namespace-level-permissions) on all [Namespaces](/namespaces) in the account.
+ This permission cannot be revoked
+- **Finance Admin**
+ - Has permissions to view [billing](/cloud/billing-and-usage) information and update payment information
+ - Otherwise, has the same permissions as Account Read-only users
+ - Can be assigned to Service Accounts by a Global Admin, but otherwise can only be assigned by an Account Owner
+
+:::note Default Role
+
+When the account is created, the initial user who logs in is automatically assigned the Account Owner role.
+If your account does not have an Account Owner, please reach out to [Support](https://temporalsupport.zendesk.com/) to assign the appropriate individual to this role.
+
+:::
+
+## Using the Account Owner role
+
+The Account Owner role (i.e., users with the Account Owner system role) holds the highest level of access in the system.
+This role configures account-level parameters and manages Temporal billing and payment information.
+It allows users to perform all actions within the Temporal Cloud account.
+
+:::tip Best Practices
+
+Temporal strongly recommends the following precautions when assigning the Account Owner role to users:
+
+- Assign the role to at least two users in your organization.
+ Otherwise, limit the number of users with this role.
+- Associate a person’s direct email address to the Account Owner, rather than a shared or generic address, so Temporal Support can contact the right person in urgent situations.
+
+This latter rule is useful for anyone on your team who may need to be contacted urgently, regardless of their Account role.
+
+:::
+
+## What are the Namespace-level permissions for users in Temporal Cloud? {#namespace-level-permissions}
+
+An Account Owner or Global Admin can assign permissions for any [Namespace](/namespaces) in an account.
+A Developer can assign permissions for a Namespace they create.
+
+For a Namespace, a user can have one of the following permissions:
+
+- **Namespace Admin:**
+ - Can [manage the Namespace](/cloud/namespaces#manage-namespaces) including identities and permissions
+ - Can create, rename, update, and delete [Workflows](/workflows) within the Namespace
+- **Write:**
+ - Can create, rename, update, and delete [Workflows](/workflows) within the Namespace
+- **Read-Only:**
+ - Can only read information from the Namespace
+
+## How to update an account-level role in Temporal Cloud {#update-roles}
+
+With Global Admin or Account Owner privileges, you can update any user's account-level [role](#account-level-roles) using either the Web UI or the tcld CLI utility.
+The Account Owner role can only be granted by existing Account Owners.
+
+For security reasons, changes to the Account Owner role must be made through Temporal Support.
+To change or delete an Account Owner, you must submit a [support ticket](https://temporalsupport.zendesk.com/).
+
+{/* How to update an account-level role in Temporal Cloud using Web UI */}
+
+### How to update an account-level role using Web UI
+
+1. In Temporal Web UI, select **Settings** in the left portion of the window.
+1. On the **Settings** page, select the user.
+1. On the user profile page, select **Edit User**.
+1. On the **Edit User** page in **Account Level Role**, select the role.
+1. Select **Save**.
+
+{/* How to update an account-level role in Temporal Cloud using tcld */}
+
+### How to update an account-level role using tcld
+
+For details, see the [tcld user set-account-role](/cloud/tcld/user/#set-account-role) command.
+
+## How to update Namespace-level permissions in Temporal Cloud {#update-permissions}
+
+You can update Namespace-level [permissions](#namespace-level-permissions) by using either Web UI or tcld.
+
+{/* How to update Namespace-level permissions for a Namespace in Temporal Cloud using Web UI */}
+
+### How to use the Web UI to update a user's permissions across multiple Namespaces
+
+1. In Temporal Web UI, select **Namespaces** in the left portion of the window.
+1. On the **Namespaces** page, select the Namespace.
+1. If necessary, scroll down to the list of permissions
+1. On the user profile page in **Namespace permissions**, select the Namespace.
+1. On the Namespace page in **Account Level Role**, select the role.
+1. Select **Save**.
+
+{/* How to update Namespace-level permissions for a user in Temporal Cloud using Web UI */}
+
+### How to use the Web UI to update permissions for multiple users within a single Namespace
+
+:::note
+
+A user with the Account Owner or Global Admin account-level [role](#account-level-roles) has Namespace Admin permissions for all Namespaces.
+
+:::
+
+1. In Temporal Web UI, select **Settings** in the left portion of the window.
+1. On the **Settings** page in the **Users** tab, select the user.
+1. On the user profile page, select **Edit User**.
+1. On the **Edit User** page in **Namespace permissions**, change the permissions for one or more Namespaces.
+1. Select **Save**.
+
+{/* How to update an account-level role in Temporal Cloud using tcld */}
+
+### How to use tcld to update Namespace-level permissions
+
+For details, see the [tcld user set-namespace-permissions](/cloud/tcld/user/#set-namespace-permissions) command.
+
+## How to delete a user from your Temporal Cloud account {#delete-users}
+
+You can delete a user from your Temporal Cloud Account by using either Web UI or tcld.
+
+:::info
+
+To delete a user, a user must have the Account Owner or Global Admin account-level [role](#account-level-roles).
+
+:::
+
+{/* How to delete a user from your Temporal Cloud account using Web UI */}
+
+### How to delete a user using Web UI
+
+1. In Temporal Web UI, select **Settings** in the left portion of the window.
+1. On the **Settings** page, find the user and, on the right end of the row, select **Delete**.
+1. In the **Delete User** dialog, select **Delete**.
+
+You can delete a user in two other ways in Web UI:
+
+- User profile page: Select the down arrow next to **Edit User** and then select **Delete**.
+- **Edit User** page: Select **Delete User**.
+
+{/* How to delete a user from your Temporal Cloud account using tcld */}
+
+### How to delete a user using tcld
+
+For details, see the [tcld user delete](/cloud/tcld/user/#delete) command.
+
+## Account-level roles and Namespace-level permissions {#account-level-roles-and-namespace-level-permissions}
+
+Temporal account-level roles and Namespace-level permissions provide access to specific Temporal Workflow and Temporal Cloud operational APIs.
+The following table provides the API details associated with each account-level role and Namespace-level permission.
+
+#### Account-level role details
+
+This table provides API-level details for the permissions granted to a user through account-level roles. These permissions are configured per user.
+
+| Permission | Read-only | Developer | Finance Admin | Global Admin | Account Owner |
+| --------------------------------- | --------- | --------- | ------------- | ------------ | ------------- |
+| CountIdentities | ✔ | ✔ | ✔ | ✔ | ✔ |
+| CreateAccountAuditLogSink | | | | ✔ | ✔ |
+| CreateAPIKey | ✔ | ✔ | ✔ | ✔ | ✔ |
+| CreateNamespace | | ✔ | | ✔ | ✔ |
+| CreateNexusEndpoint | | ✔ | | ✔ | ✔ |
+| CreateServiceAccount | | | | ✔ | ✔ |
+| CreateServiceAccountAPIKey | | | | ✔ | ✔ |
+| CreateStripeCustomerPortalSession | | | ✔ | | ✔ |
+| CreateUser | | | | ✔ | ✔ |
+| DeleteAccountAuditLogSink | | | | ✔ | ✔ |
+| DeleteAPIKey | ✔ | ✔ | ✔ | ✔ | ✔ |
+| DeleteNexusEndpoint | | ✔ | | ✔ | ✔ |
+| DeleteServiceAccount | | | | ✔ | ✔ |
+| DeleteUser | | | | ✔ | ✔ |
+| GetAccount | ✔ | ✔ | ✔ | ✔ | ✔ |
+| GetAccountAuditLogSink | | | | ✔ | ✔ |
+| GetAccountAuditLogSinks | | | | ✔ | ✔ |
+| GetAccountFeatureFlags | ✔ | ✔ | ✔ | ✔ | ✔ |
+| GetAccountLimits | ✔ | ✔ | ✔ | ✔ | ✔ |
+| GetAccountSettings | ✔ | ✔ | ✔ | ✔ | ✔ |
+| GetAccountUsage | | | | ✔ | ✔ |
+| GetAPIKey | ✔ | ✔ | ✔ | ✔ | ✔ |
+| GetAPIKeys | ✔ | ✔ | ✔ | ✔ | ✔ |
+| GetAsyncOperation | ✔ | ✔ | ✔ | ✔ | ✔ |
+| GetAuditLogs | | | | ✔ | ✔ |
+| GetDecodedCertificate | ✔ | ✔ | ✔ | ✔ | ✔ |
+| GetIdentities | ✔ | ✔ | ✔ | ✔ | ✔ |
+| GetIdentity | ✔ | ✔ | ✔ | ✔ | ✔ |
+| GetNamespaces | ✔ | ✔ | ✔ | ✔ | ✔ |
+| GetNamespacesUsage | | | | ✔ | ✔ |
+| GetNexusEndpoint | ✔ | ✔ | ✔ | ✔ | ✔ |
+| GetNexusEndpoints | ✔ | ✔ | ✔ | ✔ | ✔ |
+| GetRegion | ✔ | ✔ | ✔ | ✔ | ✔ |
+| GetRegions | ✔ | ✔ | ✔ | ✔ | ✔ |
+| GetRequestStatus | ✔ | ✔ | ✔ | ✔ | ✔ |
+| GetRequestStatuses | | | | ✔ | ✔ |
+| GetRequestStatusesForNamespace | ✔ | ✔ | ✔ | ✔ | ✔ |
+| GetRequestStatusesForUser | ✔ | ✔ | ✔ | ✔ | ✔ |
+| GetRoles | ✔ | ✔ | ✔ | ✔ | ✔ |
+| GetRolesByPermissions | ✔ | ✔ | ✔ | ✔ | ✔ |
+| GetServiceAccount | ✔ | ✔ | ✔ | ✔ | ✔ |
+| GetServiceAccounts | ✔ | ✔ | ✔ | ✔ | ✔ |
+| GetStripeInvoice | | | ✔ | | ✔ |
+| GetUser | ✔ | ✔ | ✔ | ✔ | ✔ |
+| GetUsers | ✔ | ✔ | ✔ | ✔ | ✔ |
+| GetUsersWithAccountRoles | ✔ | ✔ | ✔ | ✔ | ✔ |
+| InviteUsers | | | | ✔ | ✔ |
+| ListCreditLedgerEntries | | | ✔ | | ✔ |
+| ListGrants | | | ✔ | | ✔ |
+| ListMetronomeInvoices | | | ✔ | | ✔ |
+| ListMetronomeInvoicesForNamespace | | | ✔ | | ✔ |
+| ListNamespaces | ✔ | ✔ | ✔ | ✔ | ✔ |
+| ListPromotionGrantBalances | | | ✔ | | ✔ |
+| ResendUserInvite | | | | ✔ | ✔ |
+| SetAccountSettings | | | | ✔ | ✔ |
+| SyncCurrentUserInvite | ✔ | ✔ | ✔ | ✔ | ✔ |
+| UpdateAccount | | | | ✔ | ✔ |
+| UpdateAccountAuditLogSink | | | | ✔ | ✔ |
+| UpdateAPIKey | ✔ | ✔ | ✔ | ✔ | ✔ |
+| UpdateNexusEndpoint | | ✔ | | ✔ | ✔ |
+| UpdateServiceAccount | | | | ✔ | ✔ |
+| UpdateUser | | | | ✔ | ✔ |
+| ValidateAccountAuditLogSink | | | | ✔ | ✔ |
+
+#### Namespace-level permissions details
+
+This table provides API-level details for the permissions granted to a user through Namespace-level permissions.
+These permissions are configured per Namespace per user.
+
+:::note
+
+Account Owners and Global Admins inherit Namespace Admin permissions on all Namespaces.
+
+:::
+
+| Permission | Read | Write | Namespace Admin |
+| ---------------------------------- | ---- | ----- | --------------- |
+| CountWorkflowExecutions | ✔ | ✔ | ✔ |
+| CreateExportSink | | | ✔ |
+| CreateSchedule | | ✔ | ✔ |
+| DeleteExportSink | | | ✔ |
+| DeleteNamespace | | | ✔ |
+| DeleteSchedule | | ✔ | ✔ |
+| DescribeBatchOperation | ✔ | ✔ | ✔ |
+| DescribeNamespace | ✔ | ✔ | ✔ |
+| DescribeSchedule | ✔ | ✔ | ✔ |
+| DescribeTaskQueue | ✔ | ✔ | ✔ |
+| DescribeWorkflowExecution | ✔ | ✔ | ✔ |
+| FailoverNamespace | | | ✔ |
+| GetExportSink | ✔ | ✔ | ✔ |
+| GetExportSinks | ✔ | ✔ | ✔ |
+| GetNamespace | ✔ | ✔ | ✔ |
+| GetNamespaceUsage | ✔ | ✔ | ✔ |
+| GetReplicationStatus | ✔ | ✔ | ✔ |
+| GetSearchAttributes | ✔ | ✔ | ✔ |
+| GetUsersForNamespace | ✔ | ✔ | ✔ |
+| GetWorkerBuildIdCompatibility | ✔ | ✔ | ✔ |
+| GetWorkerTaskReachability | ✔ | ✔ | ✔ |
+| GetWorkflowExecutionHistory | ✔ | ✔ | ✔ |
+| GetWorkflowExecutionHistoryReverse | ✔ | ✔ | ✔ |
+| GlobalizeNamespace | | | ✔ |
+| ListBatchOperations | ✔ | ✔ | ✔ |
+| ListClosedWorkflowExecutions | ✔ | ✔ | ✔ |
+| ListExportSinks | ✔ | ✔ | ✔ |
+| ListFailoverHistoryByNamespace | ✔ | ✔ | ✔ |
+| ListOpenWorkflowExecutions | ✔ | ✔ | ✔ |
+| ListReplicaStatus | ✔ | ✔ | ✔ |
+| ListScheduleMatchingTimes | ✔ | ✔ | ✔ |
+| ListSchedules | ✔ | ✔ | ✔ |
+| ListTaskQueuePartitions | ✔ | ✔ | ✔ |
+| ListWorkflowExecutions | ✔ | ✔ | ✔ |
+| PatchSchedule | | ✔ | ✔ |
+| PollActivityTaskQueue | | ✔ | ✔ |
+| PollWorkflowTaskQueue | | ✔ | ✔ |
+| QueryWorkflow | ✔ | ✔ | ✔ |
+| RecordActivityTaskHeartbeat | | ✔ | ✔ |
+| RecordActivityTaskHeartbeatById | | ✔ | ✔ |
+| RenameCustomSearchAttribute | | | ✔ |
+| RequestCancelWorkflowExecution | | ✔ | ✔ |
+| ResetStickyTaskQueue | | ✔ | ✔ |
+| ResetWorkflowExecution | | ✔ | ✔ |
+| RespondActivityTaskCanceled | | ✔ | ✔ |
+| RespondActivityTaskCanceledById | | ✔ | ✔ |
+| RespondActivityTaskCompleted | | ✔ | ✔ |
+| RespondActivityTaskCompletedById | | ✔ | ✔ |
+| RespondActivityTaskFailed | | ✔ | ✔ |
+| RespondActivityTaskFailedById | | ✔ | ✔ |
+| RespondQueryTaskCompleted | | ✔ | ✔ |
+| RespondWorkflowTaskCompleted | | ✔ | ✔ |
+| RespondWorkflowTaskFailed | | ✔ | ✔ |
+| SetUserNamespaceAccess | | | ✔ |
+| SignalWithStartWorkflowExecution | | ✔ | ✔ |
+| SignalWorkflowExecution | | ✔ | ✔ |
+| StartBatchOperation | | ✔ | ✔ |
+| StartWorkflowExecution | | ✔ | ✔ |
+| StopBatchOperation | | ✔ | ✔ |
+| TerminateWorkflowExecution | | ✔ | ✔ |
+| UpdateExportSink | | | ✔ |
+| UpdateNamespace | | | ✔ |
+| UpdateSchedule | | ✔ | ✔ |
+| UpdateSearchAttributes | | | ✔ |
+| UpdateUserNamespacePermissions | | | ✔ |
+| ValidateExportSink | | | ✔ |
+| ValidateGlobalizeNamespace | | | ✔ |
+
+:::note UpdateNamespace settings
+
+`UpdateNamespace` requires Namespace Admin permission and covers these settings:
+- [Retention period](/temporal-service/temporal-server#retention-period)
+- [API key auth](/cloud/api-keys#namespace-authentication)
+- [mTLS certificates](/cloud/certificates)
+- [Certificate filters](/cloud/certificates#manage-certificate-filters)
+- [Codec server](/production-deployment/data-encryption)
+- [Connectivity rules](/cloud/connectivity)
+- [Custom Search Attributes](/search-attribute#custom-search-attribute)
+- [Provisioned capacity (TRUs)](/cloud/capacity-modes#provisioned-capacity)
+- [High Availability](/cloud/high-availability)
+
+:::
+
+## How to troubleshoot account access issues {#troubleshoot-access}
+
+### Why can't I sign in after my email domain changed? {#email-domain-change}
+
+If your organization changed its email domain (for example, from `@oldcompany.com` to `@newcompany.com`), you may be unable to sign in to Temporal Cloud with your existing account.
+
+**Why this happens:**
+When you sign in using "Continue with Google" or "Continue with Microsoft", Temporal Cloud identifies your account by your email address.
+If your email address changes, Temporal Cloud sees this as a different identity and cannot match it to your existing account.
+
+**How to resolve this:**
+[Create a support ticket](/cloud/support#support-ticket) with the following information:
+
+- Your previous email address (the one originally used to access Temporal Cloud)
+- Your new email address
+- Your Temporal Cloud Account Id (if known)
+
+Temporal Support can update your account to use your new email address.
+
+:::tip Use SAML for enterprise identity management
+
+If your organization frequently changes email domains or wants centralized control over user authentication, consider using [SAML authentication](/cloud/saml).
+With SAML, your identity provider (IdP) manages user identities, and email domain changes can be handled within your IdP without affecting Temporal Cloud access.
+
+:::
diff --git a/docs/evaluate/temporal-cloud/limits.mdx b/docs/evaluate/temporal-cloud/limits.mdx
index a166d8f8dd..dc8ae1a9f5 100644
--- a/docs/evaluate/temporal-cloud/limits.mdx
+++ b/docs/evaluate/temporal-cloud/limits.mdx
@@ -196,6 +196,18 @@ When creating custom Search Attributes in Temporal Cloud, the attribute names mu
For more information on custom Search Attributes see [Custom Search Attributes limits](/search-attribute#custom-search-attribute).
+### Custom Roles limits {#custom-role-limits}
+
+Each account can create up to 25 [Custom Roles](/cloud/manage-access/custom-roles).
+
+The UI can display up to 100 Custom Roles.
+
+There is no limit to the number of permission actions for each Custom Role.
+
+A single principal (such as a user) can be assigned up to 10 Custom Roles.
+
+A Custom Role can be applied to up to 20 specific resources (such as a Namespace). Note that applying a Custom Role to ALL resources is still supported even if there are more than 20.
+
## Nexus Endpoint level
### Nexus Endpoints limits
diff --git a/sidebars.js b/sidebars.js
index e606b87475..a4fe00cbfc 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -1116,9 +1116,10 @@ module.exports = {
},
items: [
'cloud/manage-access/roles-and-permissions',
- 'cloud/get-started/users',
+ 'cloud/manage-access/users',
'cloud/get-started/user-groups',
'cloud/get-started/service-accounts',
+ 'cloud/manage-access/custom-roles',
'cloud/saml',
'cloud/scim',
'cloud/manage-access/permissions-reference',