docs: Cloud users refactor

docs/best-practices/managing-namespace.mdx

@@ -106,7 +106,7 @@ Use a custom [Authorizer](/self-hosted-guide/security#authorizer-plugin) on your
 
 If an Authorizer is not set, Temporal uses the `nopAuthority` authorizer that unconditionally allows all API calls.
 
-On Temporal Cloud, [role-based access controls](/cloud/users#namespace-level-permissions) provide namespace-level authorization without custom configuration.
+On Temporal Cloud, [role-based access controls](/cloud/manage-access/roles-and-permissions#namespace-level-permissions) provide namespace-level authorization without custom configuration.
 
 ### Enable deletion protection (Temporal Cloud only) {#deletion-protection}
 

docs/cloud/connectivity/index.mdx

@@ -97,7 +97,7 @@ Connectivity rules can be created and managed with [tcld](https://docs.temporal.
 
 ### Permissions and limits
 
-Only [Account Admins and Account Owners](/cloud/users#account-level-roles) can create and manage connectivity rules. Connectivity rules are visible to Account Developers, Account Admins, and Account Owners.
+Only [Account Admins and Account Owners](/cloud/manage-access/roles-and-permissions#account-level-roles) can create and manage connectivity rules. Connectivity rules are visible to Account Developers, Account Admins, and Account Owners.
 
 By default each namespace is limited to 5 private connectivity rules, and each account is limited to 50 private connectivity rules. You can [contact support](/cloud/support#support-ticket) to request a higher limit.
 

docs/cloud/get-started/certificates.mdx

@@ -324,7 +324,7 @@ stricter controls, such as:
 
 :::note
 
-To manage certificates for a Namespace, a user must have [Namespace Admin](/cloud/users#namespace-level-permissions)
+To manage certificates for a Namespace, a user must have [Namespace Admin](/cloud/manage-access/roles-and-permissions#namespace-level-permissions)
 permission for that Namespace.
 
 :::

docs/cloud/get-started/index.mdx

@@ -79,4 +79,4 @@ See [Managing users](/cloud/users) to add other users and assign them roles.
 You can also use [Service Accounts](/cloud/service-accounts) to represent machine identities.
 
 Since you created the account when you signed up, your email address is the first
-[Account Owner](/cloud/users#account-level-roles) for your account.
+[Account Owner](/cloud/manage-access/roles-and-permissions#account-level-roles) for your account.

docs/cloud/get-started/namespaces.mdx

@@ -168,10 +168,10 @@ different gRPC endpoint types and how to access them.
 :::info
 
 The user who creates a [Namespace](/namespaces) is automatically granted
-[Namespace Admin](/cloud/users#namespace-level-permissions) permission for that Namespace.
+[Namespace Admin](/cloud/manage-access/roles-and-permissions#namespace-level-permissions) permission for that Namespace.
 
 To create a Namespace, a user must have the Developer, Account Owner, or Global Admin account-level
-[Role](/cloud/users#account-level-roles).
+[Role](/cloud/manage-access/roles-and-permissions#account-level-roles).
 
 :::
 
@@ -196,7 +196,7 @@ To create a Namespace in Temporal Cloud, gather the following information:
 - [Codec Server endpoint](/production-deployment/data-encryption#set-your-codec-server-endpoints-with-web-ui-and-cli) to
   show decoded payloads to users in the Event History for Workflow Executions in the Namespace. For details, see
   [Securing your data](/production-deployment/data-encryption).
-- [Permissions](/cloud/users#namespace-level-permissions) for each user.
+- [Permissions](/cloud/manage-access/roles-and-permissions#namespace-level-permissions) for each user.
 
 <Tabs>
 
@@ -393,7 +393,7 @@ On the **Edit** page, you can do the following:
   [Codec Server endpoint](/production-deployment/data-encryption#set-your-codec-server-endpoints-with-web-ui-and-cli)
   for all users on the Namespace. Each user on the Namespace has the option to
   [override this setting](/production-deployment/data-encryption#web-ui) in their browser.
-- Manage [Namespace-level permissions](/cloud/users#namespace-level-permissions).
+- Manage [Namespace-level permissions](/cloud/manage-access/roles-and-permissions#namespace-level-permissions).
 - Add users.
 
 To add a user to a Namespace, scroll to the bottom of the page and select **Add User**.
@@ -420,7 +420,7 @@ commands. For more information, see
 
 :::info
 
-To delete a Namespace, a user must have Namespace Admin [permission](/cloud/users#namespace-level-permissions) for that
+To delete a Namespace, a user must have Namespace Admin [permission](/cloud/manage-access/roles-and-permissions#namespace-level-permissions) for that
 Namespace.
 
 :::
@@ -493,7 +493,7 @@ track, and manage namespaces more easily.
 
 ### Permissions
 
-- Only [**Account Admins** and **Account Owners**](/cloud/users#account-level-roles) can create and edit tags
+- Only [**Account Admins** and **Account Owners**](/cloud/manage-access/roles-and-permissions#account-level-roles) can create and edit tags
 - All users with access to a namespace can view its tags
 
 ### tcld

docs/cloud/get-started/service-accounts.mdx

@@ -19,11 +19,11 @@ tags:
 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.
+Temporal Cloud provides Account Owner and Global Admin [roles](/cloud/manage-access/roles-and-permissions#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.
+Service Accounts afford Temporal Cloud Account Owner and Global Admin [roles](/cloud/manage-access/roles-and-permissions#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:
 
@@ -41,17 +41,17 @@ Namespace Admins can now manage and create [Namespace-scoped Service Accounts](/
 
 ## 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:
+Account Owner and Global Admin [roles](/cloud/manage-access/roles-and-permissions#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.
+Account Owner and Global Admin [roles](/cloud/manage-access/roles-and-permissions#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
+- A Cloud user account with Account Owner or Global Admin [role](/cloud/manage-access/roles-and-permissions#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`.

docs/cloud/get-started/user-groups.mdx

@@ -27,13 +27,13 @@ eases the toil of managing individual user permissions and can simplify access m
 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).
+User groups can be assigned both [account-level roles](/cloud/manage-access/roles-and-permissions#account-level-roles) and [namespace-level permissions](/cloud/manage-access/roles-and-permissions#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.
+Only users with the Account Owner or Global Admin account-level [role](/cloud/manage-access/roles-and-permissions#account-level-roles) can manage user groups.
 
 ## How SCIM groups work with user groups {#scim-groups}
 
@@ -49,7 +49,7 @@ Using user group and SCIM groups together can be useful when the groups defined
 
 :::info
 
-All user group administration requires an Account Owner or Global Admin account-level [role](/cloud/users#account-level-roles).
+All user group administration requires an Account Owner or Global Admin account-level [role](/cloud/manage-access/roles-and-permissions#account-level-roles).
 
 :::
 

docs/cloud/get-started/user-invite.mdx

@@ -20,37 +20,6 @@ tags:
   - Users
 ---
 
-:::caution
-Access to Temporal Cloud can be authorized through email and password, Google single sign-on, Microsoft single sign-on, or SAML, depending on your setup.
-
-If you are using Google OAuth for single sign-on and an email address is not associated with a Google Account, the user must follow the instructions in the [Use an existing email address](https://support.google.com/accounts/answer/27441?hl=en#existingemail) section of [Create a Google Account](https://support.google.com/accounts/answer/27441).
-
-**Important:** Do _not_ create a Gmail account when creating a Google Account.
-
-If your organization uses Google Workspace or Microsoft Entra ID, and your IT administrator has enabled controls over single sign-on permissions, then you will need to work with your IT administrator to allow logins to Temporal Cloud.
-
-:::
-
-When a user is created in Temporal Cloud, they receive an invitation email with a link.
-They must use this link to finalize their setup and access Temporal Cloud.
-Accounts with SAML configurations can ignore this email.
-However, those using Google/Microsoft SSO or email and password authentication need to accept the invitation link for their initial login to Temporal Cloud.
-For future logins, they must use the same authentication method they originally signed up with.
-
-:::info
-
-To invite users, a user must have the Global Admin or Account Owner account-level [role](/cloud/users#account-level-roles).
-
-:::
-
-### Roles and permissions
-
-Each user in Temporal Cloud is assigned a role.
-Each user can be assigned permissions for individual Namespaces.
-
-- [Account-level roles](/cloud/users#account-level-roles)
-- [Namespace-level permissions](/cloud/users#namespace-level-permissions)
-
 <Tabs>
 
 <TabItem value="invite-webui" label="Web UI">
@@ -60,89 +29,76 @@ To invite users using the Temporal Cloud UI:
 1. In Temporal Web UI, select **Settings** in the left portion of the window.
 1. On the **Settings** page, select **Create Users** in the upper-right portion of the window.
 1. On the **Create Users** page in the **Email Addresses** box, type or paste one or more email addresses.
-1. In **Account-Level Role**, select a [Role](/cloud/users#account-level-roles).
-   The Role applies to all users whose email addresses appear in **Email Addresses**.
-1. If the account has any Namespaces, they are listed under **Grant access to Namespaces**.
-   To add a permission, select the checkbox next to a Namespace, and then select a [permission](/cloud/users#namespace-level-permissions).
-   Repeat as needed.
+1. In **Account-Level Role**, select a [Role](/cloud/manage-access/roles-and-permissions#account-level-roles). The Role
+   applies to all users whose email addresses appear in **Email Addresses**.
+1. If the account has any Namespaces, they are listed under **Grant access to Namespaces**. To add a permission, select
+   the checkbox next to a Namespace, and then select a
+   [permission](/cloud/manage-access/roles-and-permissions#namespace-level-permissions). Repeat as needed.
 1. When all permissions are assigned, select **Send Invite**.
 
-Temporal sends an email message to each user.
-To join Temporal Cloud, a user must select **Accept Invite** in the message.
-
 </TabItem>
 
 <TabItem value="invite-tcld" label="tcld">
 
-To invite users using tcld, see the [tcld user invite](/cloud/tcld/user/#invite) command.
+Use the [`tcld user invite`](/cloud/tcld/user/#invite) command. Specify the user's email, an account-level role, and
+optionally one or more Namespace permissions.
 
-Temporal sends an email message to the specified user.
-To join Temporal Cloud, the user must select **Accept Invite** in the message.
+Available account roles: `admin` | `developer` | `read`.
 
-</TabItem>
+Available Namespace permissions: `Admin` | `Write` | `Read`.
 
-<TabItem value="invite-ops-api" label="Cloud Ops API">
+```command
+tcld user invite \
+  --user-email <user@example.com> \
+  --account-role <role> \
+  --namespace-permission <namespace>=<permission>
+```
 
-You can invite users pragmatically using the Cloud Ops API.
+You can invite multiple users and assign multiple Namespace permissions in a single request:
 
-1. Create a connection to your Temporal Service using the Cloud Operations API.
-2. Use the [CreateUser service](https://github.com/temporalio/api-cloud/blob/main/temporal/api/cloud/cloudservice/v1/service.proto) to create a user.
+```command
+tcld user invite \
+  --user-email user1@example.com \
+  --user-email user2@example.com \
+  --account-role developer \
+  --namespace-permission ns1=Admin \
+  --namespace-permission ns2=Write
+```
 
 </TabItem>
 
-</Tabs>
-
-### Frequently Asked Questions
-
-#### Can multiple Temporal Cloud accounts share the same email domain?
-
-Yes. Multiple Temporal Cloud accounts can coexist with users from the same email domain.
-Each account has its own independent SAML configuration, tied to its unique Account ID.
-We recommend configuring [SAML](/cloud/saml) for each account independently.
-
-For a smoother login experience, you can configure SAML for each account separately and use IdP-initiated login: you click the relevant app tile in your identity provider's portal to access the Temporal Cloud account associated with your email address directly.
-
-#### Can the same email be used across different Temporal Cloud accounts?
-
-No — each email address can only be associated with a single Temporal Cloud account.
-If you need access to multiple accounts, you’ll need a separate invite for each one using a different email address.
-
-#### Can I use Google or Microsoft SSO after signing up with email and password?
-
-If you originally signed up for Temporal Cloud using an email and password, you won’t be able to log in using Google or Microsoft single sign-on.
-
-If you prefer SSO, ask your Account Owner to delete your current user and send you a new invitation.
-During re-invitation, be sure to sign up using your preferred authentication method.
+<TabItem value="invite-ops-api" label="Cloud Ops API">
 
-#### How do I complete the `Secure Your Account` step?
+Use the [CreateUser](https://saas-api.tmprl.cloud/docs/httpapi.html#tag/users) endpoint to invite a user.
 
-If you signed up to Temporal Cloud using an email and password, you're required to set up multi-factor authentication (MFA) for added security.
-Currently, only authenticator apps are supported as an additional factor (such as Google Authenticator, Microsoft Authenticator, and Authy).
+```
+POST /cloud/users
+```
 
-To proceed:
+The request body includes a `spec` with the following fields:
 
-1. Download a supported authenticator app on your mobile device.
-2. Scan the QR code shown on the **Secure Your Account** screen.
-3. Enter the verification code from your app to complete MFA setup.
-4. Securely store your recovery code.
-   This code allows you to access your account if you lose access to your authenticator app.
+- `spec.email` — The email address of the user to invite.
+- `spec.access.account_access.role` — The account-level role to assign.
+- `spec.access.namespace_accesses` — A map of Namespace names to permissions.
 
-Once MFA is configured, you’ll be able to continue using Temporal Cloud.
+Available roles: `ROLE_ADMIN` | `ROLE_DEVELOPER` | `ROLE_READ` | `ROLE_OWNER` | `ROLE_FINANCE_ADMIN`.
 
-#### What if I lose access to my authenticator app?
+Available Namespace permissions: `PERMISSION_ADMIN` | `PERMISSION_WRITE` | `PERMISSION_READ`.
 
-If you lose access to your authenticator app, you can still log in by clicking **Try another method** on the MFA screen.
-From there, you can either:
+</TabItem>
 
-- Enter your recovery code (provided when you first set up MFA)
-- Receive a verification code through email
+</Tabs>
 
-Once you're logged in, you can reset your authenticator app by navigating to **My Profile** > **Password and Authentication** and then clicking **Authenticator App** > **Remove method**.
+The new users receive an email with a link to accept the invitation and complete their setup. The new user must use this
+link to sign up to be added to your account unless the account has a SAML configuration. If your account has a SAML
+configuration, the new user can sign in using their existing SAML credentials and be included in the account
+automatically.
 
-#### How do I reset my password?
+:::caution
 
-If you're currently logged in and would like to change your password, click your profile icon at the top right of the Temporal Cloud UI,
-navigate to **My Profile** > **Password and Authentication**, and then click **Reset Password**.
+The new user must use the same authentication method they originally signed up with to sign in to Temporal Cloud. If
+they used single sign-on (SSO), they must use the same SSO provider to sign in to Temporal Cloud. If they used email and
+password authentication, they must use the same email and password to sign in to Temporal Cloud, and cannot use SSO,
+even if the underlying email address is the same.
 
-If you're not currently logged in, navigate to the login page of the Temporal Cloud UI, enter your email address, click **Continue**, and then select **Forgot password**.
-In both cases, you will receive an email with instructions on how to reset your password.
+:::