--- description: Four identities, each with the smallest scope that does its job. This page records which identity reaches each source. --- # Credentials and permissions Four identities, each with the smallest scope that does its job. This page records which identity reaches each source. Endpoint availability varies by plan, region and product rollout, so a deployment records the actual HTTP status and coverage rather than turning an unavailable source into a zero. ## The org-realm reader `collector.config.READER_SCOPES` is authoritative. One org-realm token reaches all four signal databases in every region of the estate - the region hint in the token payload does not constrain the data plane. | Scope | Reaches | Basic-auth user | |---|---|---| | `stacks:read` | Grafana.com stack inventory | bearer | | `stack-users:read` | per-stack users through Grafana.com | bearer | | `stack-plugins:read` | per-stack plugins through Grafana.com | bearer | | `org-members:read` | organisation membership | bearer | | `accesspolicies:read` | regional access-policy inventory | bearer | | `metrics:read` | Mimir cardinality API **and the whole Prometheus query API** | `hmInstancePromId` | | `logs:read` | Loki label and label-value endpoints | `hlInstanceId` | | `traces:read` | Tempo search-tag endpoints | `htInstanceId` | | `profiles:read` | Pyroscope `LabelValues` | `hpInstanceId` | | `rules:read` | Prometheus and Loki ruler inventory | signal instance id | | `alerts:read` | Alertmanager status, alerts and silences | `amInstanceId` | | `adaptive-metrics-rules:read` | `/aggregations/rules` | `hmInstancePromId` | | `adaptive-metrics-recommendations:read` | `/aggregations/recommendations?verbose=true` | `hmInstancePromId` | | `adaptive-metrics-config:read` | `/aggregations/recommendations/config` | `hmInstancePromId` | | `fleet-management:read` | Fleet Management Connect-RPC list methods | stack `id` | The basic-auth user differs per signal and comes from `dataplane.AUTH_FIELD`. Fleet Management and the Alertmanager are the two that do not use a signal instance id. Fleet calls use POST because that is the RPC transport. The scope and the methods remain reads, and they live outside the collector's HTTP client - which rejects every method except GET. Grafana.com is paced at six requests per second. Paused stacks are skipped when the control plane answers with its paused-stack conflict response. Two things the org token deliberately does not have: - **`adaptive-metrics-exemptions:read`** is declared to match the deployed policy, but no path has answered 200. Eight candidates under `/aggregations` were tried and all 404. Treat it as reserved, not as a capability, until a route is verified. - **`stack-service-accounts:read` does not exist.** Only the write scope does, so it is not given to the collector. Service-account inventory is reached through each stack's local reader instead. ### The two scopes that reach beyond inventory `alerts:read` and `rules:read` are not free, and the collector must not treat them as such. - **`/alertmanager/api/v2/status` returns the stack's raw Alertmanager configuration** in `config.original`, `http_config` included. Where a stack's contact points live in Alertmanager rather than in Grafana, that YAML can carry webhook URLs and tokens. Nothing derived from that body may be stored, logged or emitted beyond bounded counts. - **`/api/prom/api/v1/alerts` returns firing instances with their full customer label sets.** Unbounded and identity-bearing. Count them; never carry them into a metric label. - The Loki ruler answers **404 with `no rule groups found`** when a stack has no rules. That is an empty inventory, not a permission failure. `/prometheus/api/v1/rules` on the same host returns 200 with an empty group list for the same stack, so prefer it and read the 404 as zero. ## The stack-local reader The provisioner declares `collector.provision.DESIRED_PERMISSIONS`. It creates a basic-role-`None` service account on each stack and assigns `custom:gcinsight.reader`. Drift is compared as action/scope pairs, not action names. The role can read: - Assistant aggregate usage, tenant-scoped inventory and investigations counts; - Adaptive Logs recommendations through the plugin-proxy route; - service-account inventory and permission metadata; - datasource metadata and caching state; - folders, dashboards, public dashboards and snapshots; - teams, team permissions, team roles, user roles and custom-role metadata; - alert-rule and receiver inventory, without receiver secrets; - the datasource proxy for exactly `grafanacloud-usage-insights`. `datasources:read` uses `datasources:*` because it lists metadata. `datasources:query` is separately pinned to `datasources:uid:grafanacloud-usage-insights` and is never widened to `datasources:*`. The reader cannot query arbitrary production datasources. The declaration explicitly refuses decrypted alert secrets, secure values, user session tokens, Grafana auth settings, support bundles, provisioning writes and Adaptive Traces mutation actions. `chats:access` is not granted. **Several list endpoints return HTTP 200 with a permission-filtered empty list.** Coverage is therefore part of the result, and a zero is trusted only after the matching role pair is confirmed present. ## Write identities The runtime writer carries only `metrics:write` and `logs:write`, in the nominated write stack's realm. It cannot touch any other stack because the realm forbids it, not because a scope check says so. The provisioner carries `stacks:read` and `stack-service-accounts:write`, and is a separate scheduled task with a separate secret key. Build-time Grafana credentials are supplied only to the dashboard and alert publication tools, and should be short-lived. ## Source-specific contracts ### Usage insights Each stack's usage-insights datasource exposes a **regional** tenant, so every query made with that stack's own reader includes `instance_type="grafana"` and `instance_id=""`. The label is the stack `id` for Grafana events, not its Prometheus tenant id. The query helper refuses a selector without `instance_id`. Get it wrong and one stack's figures are repeated across every stack in its region, with nothing failing. ### Adaptive Metrics `?verbose=true` is required for series counts. The default response is structurally complete-looking and insufficient for savings arithmetic. ### Adaptive Logs The working read route is the Adaptive Logs plugin proxy. Frontend app resource paths can return 500, and datasource-proxy calls can report authentication failure even when the reader role is correct. Recommendation volume has no declared or settable time window. ### Assistant The working route is the Assistant app's plugin-resource proxy, and usage endpoints take epoch milliseconds. Tenant-scoped objects are readable. User-scoped objects are invisible to every other identity and cannot be counted as estate inventory - that is a product boundary, not a reason to widen the role. ### Public dashboards Enumeration and usage events are separate. The stack API enumerates configured shares including ones nobody opens; usage-insights events identify public shares observed in use. `accessToken` is the live public URL and is never stored, logged or emitted. ### Alert routing The reader collects rule and receiver names, not decrypted receiver configuration. A rule with no direct receiver inherits the stack notification policy; that is reported as routing exposure, not automatically labelled broken. ## Known unavailable or rejected routes - Synthetic Monitoring result inventory has no verified safe unattended read route. - Adaptive Profiles endpoints have not produced a verified read contract. - Adaptive Traces collection is absent until a concrete read-only consumer and permission contract exist. - Regional usage-insights datasources on one central stack are not a substitute for per-stack readers. - Grafana.com dashboard lists are incomplete or empty; stack-local APIs own that inventory.