jackson2w/claude-code-skills / grafana-api-token-provisioning
grafana-api-token-provisioning
VerifiedThis 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:$PWfor 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. Returnsdata.groups[].rules[], each withhealth(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/healthalone, 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 319k | Updated | Claude CodeCodex | Verified | Install |
| 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: 196k | Updated | Claude CodeCodex | Verified | Install |
| 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: 196k | Updated | Claude CodeCodex | Verified | Install |
| 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: 196k | Updated | Claude CodeCodex | Verified | Install |