Skip to content

jackson2w/claude-code-skills / grafana-api-token-provisioning

grafana-api-token-provisioning

Verified

This skill should be used when provisioning a scoped Grafana API credential for an automation/script (a monitoring sweep, a health-check script, a report generator), when deciding what Grafana role a service account needs, when checking real alert-rule health/evaluation state via the API rather than the UI, or when a Grafana RBAC fixed role like `fixed:alerting.rules:reader` doesn't seem to be assignable. Trigger phrases include "grafana service account", "grafana api token", "grafana read-only token", "grafana alert rule health api", "api/prometheus/grafana/api/v1/rules", "fixed:alerting.rules:reader not available", "grafana RBAC OSS vs enterprise", "grafana viewer role least privilege".

Grafana API token provisioning: OSS role ceiling + useful read endpoints

OSS has no granular RBAC — Viewer is the floor, not a narrow scope

Grafana's fine-grained fixed roles (fixed:alerting.rules:reader, fixed:alerting.instances:reader, fixed:alerting:reader, fixed:annotations:reader, etc.) are Enterprise/Cloud-only — confirmed against current docs (checked against a live Grafana 13.1.0 OSS install, 2026-07-27). An unlicensed OSS install can only assign the three basic org roles to a service account: Viewer, Editor, Admin.

This means "least privilege" for OSS Grafana tops out at Viewer — which reads all dashboards, datasource configs, and alerting state in the org, not just the one thing the automation actually needs. Say this explicitly when proposing a token to a human ("Viewer is the finest grain OSS offers, broader than ideal") rather than implying true narrow scoping was achieved — don't oversell the privilege boundary.

Don't spend time hunting for a way to assign a fixed role via the API on an OSS instance — it's not a permissions or syntax problem, it's a licensing gate. Check grafana.ini/the org's license status first if genuinely unsure whether Enterprise features are active.

Creating a service account + token via API (no UI needed)

# 1. Create the service account (role: Viewer | Editor | Admin)
curl -s -u "admin:$ADMIN_PW" -X POST http://<host>:3000/api/serviceaccounts \
  -H "Content-Type: application/json" \
  -d '{"name":"my-automation-ro","role":"Viewer"}'
# -> {"id":2,"uid":"...","name":"my-automation-ro","role":"Viewer","tokens":0,...}

# 2. Create a token for it (secondsToLive sets expiration; omit for no expiration —
#    prefer setting one, e.g. 31536000 = 1 year, to bound blast radius of a leak)
curl -s -u "admin:$ADMIN_PW" -X POST http://<host>:3000/api/serviceaccounts/2/tokens \
  -H "Content-Type: application/json" \
  -d '{"name":"my-token","secondsToLive":31536000}'
# -> {"id":1,"name":"my-token","key":"glsa_..."}   <- key is shown exactly ONCE, capture it now

The key field is the only time the raw token is ever returned — if it's lost, delete the token and mint a new one, don't try to recover it. Pipe the extraction straight into the credential file in one command (e.g. via python3 -c 'import sys,json; print(json.load(sys.stdin)["key"])') so it never lands in shell history or chat output — see credential-rotation-protocol for the general "never cat a secret back" discipline this falls under.

Store as /root/.config/<service>-api-token.env (600, root-owned), same convention as every other homelab credential (tailscale-oauth.env, immich-admin.env, etc.) — a plain directory outside any git repo, doubly safe even before *.env gitignore rules apply.

Useful read-only endpoints for a Viewer-role token

  • GET /api/health — basic liveness (database: ok), needs no auth at all.
  • GET /api/user — confirms a credential authenticates (-u admin:$PW for the admin account itself, or -H "Authorization: Bearer $TOKEN" for a service account token).
  • GET /api/prometheus/grafana/api/v1/rules — the Prometheus-compatible ruler API. Returns data.groups[].rules[], each with health (ok/error/nodata), state (inactive/pending/alerting), lastEvaluation, evaluationTime. This is the endpoint for "is alerting actually evaluating cleanly" — far more useful for a health-sweep script than /api/health alone, and works fine under a plain Viewer role. (Grafana 13 is migrating /api/* toward /apis/* long-term, but the legacy path remains fully functional — no urgency to switch.)

Always verify the negative alongside the positive: an unauthenticated call to the rules endpoint should return 401, confirming it's genuinely gated rather than coincidentally open.

Example: turning a "not provisioned yet" warn into a real check

A health-sweep script that can't yet get a scoped credential should emit an honest warn explaining why (not silently skip the check) — then, once a human confirms provisioning is wanted, the checker should source the token file conditionally and degrade gracefully back to the warn if the file is ever missing (e.g. after a host rebuild), rather than hard-failing the whole sweep on a missing credential. See the homelab weekly-housekeeping-checks.sh's grafana_alert_history_scope check (added 2026-07-27) for a worked example of this pattern.

brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 319kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 196kUpdated Claude CodeCodexVerifiedInstall