Skip to main content
Connect a Grafana instance so CloudThinker can work from the dashboards, data sources, and alert rules your team already has. Agents can find the right dashboard, run Prometheus or Loki queries through Grafana, and tell you which alerts are firing, without you copying panels into chat. The connection signs in with a service account token, a non-human Grafana identity you create and scope to the Viewer role.

​
Supported platforms

​
Prerequisites

  • A Grafana instance reachable from the public internet over HTTPS. Connections run from CloudThinker Cloud, so a private instance needs one of the options in Reaching private services. If you firewall it, allow CloudThinker’s egress IPs. These docs don’t publish CloudThinker’s egress IP list: ask your CloudThinker contact, or contact us.
  • A valid, publicly trusted TLS certificate. Self-signed certificates fail.
  • Grafana admin access to create a service account.
  • One connection per Grafana organization. A service account sees only the organization it was created in, so for several orgs, create a service account in each and add a connection for each.
  • The Admin role in your CloudThinker workspace, which can add and edit connections. See Roles.

​
Setup

1

Create a Viewer service account

In Grafana, go to Administration → Users and access → Service accounts and click Add service account. Set:
  • Display name: cloudthinker-readonly
  • Role: Viewer
Click Create.
2

Generate a token

On the new service account’s page, click Add service account token, name it (for example cloudthinker), set an expiration such as 90 days, and click Generate token. When the token expires, the connection fails with a 401 until you replace it. See Token expired.Copy the token now. It starts with glsa_, and Grafana won’t show it again.
3

Add the connection in CloudThinker

Open More → Workspace settings → Connections, stay on the Builtin Connections tab, and select Grafana. Fill in:
  • GRAFANA_URL: your instance’s base URL, such as https://grafana.example.com or https://your-stack.grafana.net
  • GRAFANA_SERVICE_ACCOUNT_TOKEN: the glsa_ token
  • Alias and Description: optional. Agents read the description to pick the right instance, so name the org or environment if you add more than one
Click Connect.Success state: the connection shows Connecting and Verifying, then Connected. If verification fails, it shows Failed and an error message appears. Match the message to Troubleshooting.

​
Connection details

​
Required permissions

Agents see only what the service account can see. If a dashboard folder has restricted permissions, add the service account to that folder or agents won’t find its dashboards.
Keep the service account on Viewer. Grafana then refuses any change on its side, whatever an agent asks for.

​
Agent capabilities

Agents query through Grafana, so a data source only works if it’s configured in your Grafana instance and the service account can use it. When Grafana is connected, Resolve can also read your alert rules and query metric ranges while it investigates an incident. Sending Grafana alerts into Resolve is a separate webhook setup: see Webhook integrations.

​
Verify the connection

Expect the names and states of firing rules (or a note that none are firing), then each data source with its type, such as Prometheus or Loki.

​
Example prompts

​
Write access

The connection can call Grafana tools that change things, such as editing a dashboard, adding an annotation, or changing an alert rule. Any call that changes something goes through Approvals, and Grafana only allows it if the service account’s role does. With Viewer, Grafana refuses all of them. Every change an agent makes goes through your workspace’s Approvals first. On the default Auto · Rules + AI · Ask me mode, AI judgment can let a safe change run without asking — and an Allow Rule can too, once CloudThinker turns on Rule enforcement for your workspace. Choose Manual to approve every change yourself. There’s no Allow writes switch on this connection, so CloudThinker has no read-only setting of its own here. The service account’s Grafana role is what blocks writes, so keep it on Viewer unless you want changes.

​
Troubleshooting

  • Open GRAFANA_URL from a browser outside your network to check it’s reachable from the internet, or allow CloudThinker through your firewall.
  • Check that the TLS certificate is valid and not self-signed.
  • Use the base URL only, without a dashboard path.
  • Recheck the token. Copy it again if a character was lost.
  • Check that the token hasn’t expired and the service account is enabled in Administration → Users and access → Service accounts.
Open the service account in Grafana, generate a new token, and paste it into GRAFANA_SERVICE_ACCOUNT_TOKEN on the connection. Delete the old token in Grafana.
The dashboard sits in a folder the service account can’t view. Grant the service account View on that folder.
Your own access in Explore doesn’t prove the service account’s. Check two things:
  • On Grafana Enterprise or Cloud, open the data source’s Permissions tab and confirm the service account (or a role it has) can query it.
  • Test as the service account: curl -H "Authorization: Bearer glsa_..." https://<grafana>/api/datasources. If the data source is missing from the response, the service account can’t use it.
Agents can only query data sources that Grafana itself can query.
Those are Grafana Cloud features. They work only if your stack has them turned on. Some Grafana Cloud apps have their own access roles, so if Viewer isn’t enough, check the app’s role settings for the service account in Grafana.

​
Security

  • Least privilege — grant only the permissions the agents need for your use case; start read-only and widen later.
  • Read-only by default — use read-only credentials unless you want agents to make changes through this connection.
  • Rotate credentials — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
  • Revoke on offboarding — remove the credential at the provider when you delete a connection or a teammate leaves.
  • Viewer only: give the CloudThinker service account Viewer, never Admin.
  • Expiring tokens: set an expiration on every token and rotate it on your normal schedule.

Prometheus

Query Prometheus directly when it isn’t behind Grafana.

Webhook integrations

Send Grafana alerts into Resolve so investigations start on their own.