Grafana Service Accounts

People are not the only visitors to Grafana. Scripts create dashboards, deployment tools add annotations, and backup jobs export configuration. These programs need a safe way to prove who they are. Service accounts give each program its own identity, its own role, and its own revocable tokens.

The Visitor Badge Analogy

A company hands badges to contractors who deliver parcels or fix equipment. Each badge opens only the doors that the job requires, carries an expiry date, and the guard cancels it when the work ends. For software, a service account plays the role of that badge for software. A token proves identity, a role limits access, and the administrator can cancel the token at any time.

+-------------+     token      +---------------+
| Backup      | ------------>  |   Grafana     |
| Script      |                |   API         |
+-------------+                +-------+-------+
 (service account:                     |
  role = Viewer)                 allowed: read
                                 denied:  delete

Why Service Accounts Replace Shared Logins

Some teams let scripts log in with a human username and password. That habit creates risks. Anyone who knows the password gains the full rights of that person. Password changes break every script at once. Audit logs blame a person for actions a machine performed.

Service accounts remove those problems. Each program has a separate identity, so logs name the right actor. Tokens carry only the rights the job needs. Cancelling one token leaves every other program running.

Create a Service Account

1. Open Administration, go to Users and access, and select Service accounts.
2. Click Add service account.
3. Type a display name that describes the job, such as dashboard-backup.
4. Choose a role: Viewer, Editor, or Admin.
5. Click Create.

Pick the lowest role that works. A backup script that only reads dashboards needs the Viewer role.

Create a Token

Open the new service account and click Add service account token. Give the token a name and an expiry date. Click Generate token.

Grafana shows the token exactly once. Copy it immediately and store it in a password manager or a secrets vault. Nobody, including administrators, can read it again later. Lose the token and you must generate a new one.

Use a Token

Send the token in an HTTP header named Authorization, prefixed with the word Bearer.

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "http://localhost:3000/api/search?type=dash-db"

The call returns a list of dashboards in JSON format. Every Grafana API call follows the same pattern.

[
  { "title": "Web Servers", "uid": "abc123", "type": "dash-db" },
  { "title": "Database",    "uid": "def456", "type": "dash-db" }
]

Common Jobs for Service Accounts

Job	Suggested Role
Export dashboards for backup	Viewer
Add deployment markers as annotations	Editor
Publish dashboards from a code repository	Editor
Manage users and teams automatically	Admin

Add an Annotation From a Pipeline

A deployment tool can mark every release on your charts.

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"Release 2.4 deployed","tags":["deploy"]}' \
  http://localhost:3000/api/annotations

Chart with release markers

CPU |      /\                     |
    |  ___/  \___        ________ |
    |             \______/        |
    +-----------|---------|-------+
              v2.3      v2.4

Manage Tokens Over Time

Set Expiry Dates

Short-lived tokens limit the damage of a leak. Choose a date within a year, and shorter for sensitive work.

Rotate Tokens

Create a new token, update the program, confirm it works, and delete the old token. Repeat on a schedule.

Disable Unused Accounts

Switch off a service account when its job ends. A disabled account rejects all of its tokens at once.

Safe Handling Rules

• Never paste a token into a chat, a ticket, or a public repository.
• Store tokens in a secrets manager, and load them through environment variables.
• Give each program its own service account.
• Review the service account list every quarter and remove unknown entries.
• Revoke a token the moment you suspect exposure.

Older API Keys

Earlier Grafana versions used API keys for the same purpose. Service accounts replace them, and Grafana provides a migration option in the API keys page. Move to service accounts to gain better control and clearer audit trails.