From 658bd15f17f8ab9613012ee5b321815c596ca83b Mon Sep 17 00:00:00 2001 From: Dustin Cote Date: Wed, 16 Sep 2026 10:22:41 -0400 Subject: [PATCH 1/2] Document Metrics Read-Only role permissions --- docs/cloud/get-started/api-keys.mdx | 9 +++++---- .../manage-access/permissions-reference.mdx | 5 +++++ .../manage-access/roles-and-permissions.mdx | 19 ++++++++++++------- docs/cloud/manage-access/service-accounts.mdx | 4 ++++ 4 files changed, 26 insertions(+), 11 deletions(-) diff --git a/docs/cloud/get-started/api-keys.mdx b/docs/cloud/get-started/api-keys.mdx index fca6898943..5dae343b80 100644 --- a/docs/cloud/get-started/api-keys.mdx +++ b/docs/cloud/get-started/api-keys.mdx @@ -425,10 +425,11 @@ Temporal API keys automatically expire based on the specified expiration time. [ :::tip -Service Accounts can rotate their own API keys irrespective of their configured permissions. To use this feature, have -your Service Account create a new API key using the [Cloud Ops APIs](/ops) or the CLI before the current -one expires. Service Accounts cannot delete their own API keys without the requisite permissions, which helps keep -Workflow access secure. +Except for Service Accounts with the Metrics Read-Only role, Service Accounts can create replacement API keys for +themselves regardless of their configured permissions. To use this feature, have your Service Account create a new API +key using the [Cloud Ops APIs](/ops) or the CLI before the current one expires. An Account Owner or Global Admin must +create and rotate keys for Metrics Read-Only Service Accounts. Service Accounts cannot delete their own API keys without +the requisite permissions, which helps keep Workflow access secure. ::: diff --git a/docs/cloud/manage-access/permissions-reference.mdx b/docs/cloud/manage-access/permissions-reference.mdx index 9b38a84c95..1380d6a000 100644 --- a/docs/cloud/manage-access/permissions-reference.mdx +++ b/docs/cloud/manage-access/permissions-reference.mdx @@ -24,9 +24,14 @@ supports the following account-level roles: - Developer - Finance Admin - Read-Only +- Metrics Read-Only ### Cloud Ops API permissions +The Metrics Read-Only role grants no Cloud Ops API permissions, so it is not included in the following table. It grants +access only to the [Temporal Cloud OpenMetrics endpoint](/cloud/metrics/openmetrics). An Account Owner or Global Admin +must create and rotate API keys for a Service Account with this role. + This table provides API-level details for permissions granted through account-level roles. These permissions are configured per user. diff --git a/docs/cloud/manage-access/roles-and-permissions.mdx b/docs/cloud/manage-access/roles-and-permissions.mdx index 4831282226..dd93318997 100644 --- a/docs/cloud/manage-access/roles-and-permissions.mdx +++ b/docs/cloud/manage-access/roles-and-permissions.mdx @@ -25,13 +25,18 @@ such as: The following table provides a summary of the account-level roles and their primary purpose. Refer to the [Permissions reference](/cloud/manage-access/permissions-reference#account-level-access) for API-level details. -| Role | Primary purpose | Can create Namespaces | Automatic Namespace Admin | Billing and usage access | -| ------------- | ------------------------------------------- | --------------------- | --------------------------------------- | --------------------------------- | -| Account Owner | Owns and governs the account | Yes | All Namespaces (cannot be revoked) | Full billing, payments, and usage | -| Global Admin | Administers account configuration and users | Yes | All Namespaces (cannot be revoked) | Usage only | -| Developer | Creates and manages Namespaces they own | Yes | Namespaces they create (can be revoked) | None | -| Finance Admin | Manages billing and payment information | No | None | Full billing, payments, and usage | -| Read-Only | Views account configuration and resources | No | None | None | +| Role | Primary purpose | Can create Namespaces | Automatic Namespace Admin | Billing and usage access | +| ----------------- | ---------------------------------------------- | --------------------- | --------------------------------------- | --------------------------------- | +| Account Owner | Owns and governs the account | Yes | All Namespaces (cannot be revoked) | Full billing, payments, and usage | +| Global Admin | Administers account configuration and users | Yes | All Namespaces (cannot be revoked) | Usage only | +| Developer | Creates and manages Namespaces they own | Yes | Namespaces they create (can be revoked) | None | +| Finance Admin | Manages billing and payment information | No | None | Full billing, payments, and usage | +| Read-Only | Views account configuration and resources | No | None | None | +| Metrics Read-Only | Reads account metrics from the OpenMetrics API | No | None | None | + +The Metrics Read-Only role is intended for Service Accounts used by observability integrations. It grants access to the +[Temporal Cloud OpenMetrics endpoint](/cloud/metrics/openmetrics) but no Cloud Ops API or Namespace permissions. An +Account Owner or Global Admin must manage the Service Account and its API keys. Account-level roles don't govern day-to-day operations within a Namespace. Access to resources inside a Namespace, such as Workflows and Workflow Executions, is controlled by [Namespace-level permissions](#namespace-level-permissions). diff --git a/docs/cloud/manage-access/service-accounts.mdx b/docs/cloud/manage-access/service-accounts.mdx index e81dfdeef3..c8e8c55b12 100644 --- a/docs/cloud/manage-access/service-accounts.mdx +++ b/docs/cloud/manage-access/service-accounts.mdx @@ -44,6 +44,10 @@ Account Owner and Global Admin [roles](/cloud/manage-access/users#account-level- Account Owner and Global Admin [roles](/cloud/manage-access/users#account-level-roles) also have the ability to manage API Keys for Service Accounts. +Service Accounts with the Metrics Read-Only role cannot create, update, or delete API keys, including their own. An +Account Owner or Global Admin must create and rotate their keys. For setup instructions, see +[Set up Cloud metrics with OpenMetrics](/cloud/metrics/openmetrics). + ### Prerequisites - A Cloud user account with Account Owner or Global Admin [role](/cloud/manage-access/users#account-level-roles) permissions From 4905c3222fa393190483ebbe7c1ec2b6a59ea4ae Mon Sep 17 00:00:00 2001 From: Dustin Cote Date: Wed, 16 Sep 2026 11:02:20 -0400 Subject: [PATCH 2/2] Centralize Metrics Read-Only role guidance --- docs/cloud/get-started/api-keys.mdx | 10 +++++----- docs/cloud/manage-access/permissions-reference.mdx | 5 ++--- docs/cloud/manage-access/roles-and-permissions.mdx | 6 +++--- docs/cloud/manage-access/service-accounts.mdx | 5 ++--- docs/cloud/metrics/openmetrics/index.mdx | 10 +++++++++- 5 files changed, 21 insertions(+), 15 deletions(-) diff --git a/docs/cloud/get-started/api-keys.mdx b/docs/cloud/get-started/api-keys.mdx index 5dae343b80..3156262493 100644 --- a/docs/cloud/get-started/api-keys.mdx +++ b/docs/cloud/get-started/api-keys.mdx @@ -425,11 +425,11 @@ Temporal API keys automatically expire based on the specified expiration time. [ :::tip -Except for Service Accounts with the Metrics Read-Only role, Service Accounts can create replacement API keys for -themselves regardless of their configured permissions. To use this feature, have your Service Account create a new API -key using the [Cloud Ops APIs](/ops) or the CLI before the current one expires. An Account Owner or Global Admin must -create and rotate keys for Metrics Read-Only Service Accounts. Service Accounts cannot delete their own API keys without -the requisite permissions, which helps keep Workflow access secure. +Service Accounts can create replacement API keys for themselves regardless of their configured permissions, except for +Service Accounts with the [Metrics Read-Only role](/cloud/metrics/openmetrics#metrics-read-only-role). To use this +feature, have your Service Account create a new API key using the [Cloud Ops APIs](/ops) or the CLI before the current +one expires. Service Accounts cannot delete their own API keys without the requisite permissions, which helps keep +Workflow access secure. ::: diff --git a/docs/cloud/manage-access/permissions-reference.mdx b/docs/cloud/manage-access/permissions-reference.mdx index 1380d6a000..05ac6424e0 100644 --- a/docs/cloud/manage-access/permissions-reference.mdx +++ b/docs/cloud/manage-access/permissions-reference.mdx @@ -28,9 +28,8 @@ supports the following account-level roles: ### Cloud Ops API permissions -The Metrics Read-Only role grants no Cloud Ops API permissions, so it is not included in the following table. It grants -access only to the [Temporal Cloud OpenMetrics endpoint](/cloud/metrics/openmetrics). An Account Owner or Global Admin -must create and rotate API keys for a Service Account with this role. +The Metrics Read-Only role grants no Cloud Ops API permissions, so it is not included in the following table. For its +permissions and API key requirements, see [Metrics Read-Only role](/cloud/metrics/openmetrics#metrics-read-only-role). This table provides API-level details for permissions granted through account-level roles. These permissions are configured per user. diff --git a/docs/cloud/manage-access/roles-and-permissions.mdx b/docs/cloud/manage-access/roles-and-permissions.mdx index dd93318997..d1c6912435 100644 --- a/docs/cloud/manage-access/roles-and-permissions.mdx +++ b/docs/cloud/manage-access/roles-and-permissions.mdx @@ -34,9 +34,9 @@ The following table provides a summary of the account-level roles and their prim | Read-Only | Views account configuration and resources | No | None | None | | Metrics Read-Only | Reads account metrics from the OpenMetrics API | No | None | None | -The Metrics Read-Only role is intended for Service Accounts used by observability integrations. It grants access to the -[Temporal Cloud OpenMetrics endpoint](/cloud/metrics/openmetrics) but no Cloud Ops API or Namespace permissions. An -Account Owner or Global Admin must manage the Service Account and its API keys. +The Metrics Read-Only role is intended for Service Accounts used by observability integrations. It grants read access to +the [Temporal Cloud OpenMetrics endpoint](/cloud/metrics/openmetrics) but no other permissions. An Account Owner or +Global Admin must manage the Service Account and its API keys. Account-level roles don't govern day-to-day operations within a Namespace. Access to resources inside a Namespace, such as Workflows and Workflow Executions, is controlled by [Namespace-level permissions](#namespace-level-permissions). diff --git a/docs/cloud/manage-access/service-accounts.mdx b/docs/cloud/manage-access/service-accounts.mdx index c8e8c55b12..b288ad35ff 100644 --- a/docs/cloud/manage-access/service-accounts.mdx +++ b/docs/cloud/manage-access/service-accounts.mdx @@ -44,9 +44,8 @@ Account Owner and Global Admin [roles](/cloud/manage-access/users#account-level- Account Owner and Global Admin [roles](/cloud/manage-access/users#account-level-roles) also have the ability to manage API Keys for Service Accounts. -Service Accounts with the Metrics Read-Only role cannot create, update, or delete API keys, including their own. An -Account Owner or Global Admin must create and rotate their keys. For setup instructions, see -[Set up Cloud metrics with OpenMetrics](/cloud/metrics/openmetrics). +For permissions and API key requirements for Metrics Read-Only Service Accounts, see +[Metrics Read-Only role](/cloud/metrics/openmetrics#metrics-read-only-role). ### Prerequisites diff --git a/docs/cloud/metrics/openmetrics/index.mdx b/docs/cloud/metrics/openmetrics/index.mdx index cb4730ef11..b73c5b0a87 100644 --- a/docs/cloud/metrics/openmetrics/index.mdx +++ b/docs/cloud/metrics/openmetrics/index.mdx @@ -20,13 +20,21 @@ Future pricing may apply to high-volume usage that exceeds standard [limits](/cl Temporal Cloud's [OpenMetrics](https://openmetrics.io/) endpoint provides operational metrics for your Temporal Cloud workloads in industry-standard Prometheus format, enabling comprehensive monitoring across Namespaces, Workflows, and Task Queues with your existing observability stack. +## Metrics Read-Only role {/* #metrics-read-only-role */} + +Metrics Read-Only is an account-level role intended for Service Accounts that scrape the OpenMetrics endpoint. It grants +read access to the OpenMetrics endpoint but no other permissions. + +An Account Owner or Global Admin must create and manage the Service Account and all of its API keys. A Metrics Read-Only +Service Account cannot create, update, or delete API keys, including its own. + ## Quickstart Stream metrics from Temporal Cloud into your observability tool in about 5 minutes. **Prerequisites** -- An **Account Owner** or **Global Admin** role on the Temporal Cloud account. The Metrics Read-Only role is an account-level role and can only be granted by these roles. A Namespace Admin cannot complete these steps. +- An **Account Owner** or **Global Admin** role on the Temporal Cloud account. The [Metrics Read-Only role](#metrics-read-only-role) can only be granted by these roles. A Namespace Admin cannot complete these steps. - An account in the observability tool you want to use, such as Datadog, Grafana Cloud, New Relic, ClickStack, or self-hosted Prometheus. **Steps**