Grafana service accounts and API tokens

Grafana service accounts and API tokens for scripts and pipelines

A platform team that automates Grafana, for example a pipeline that creates dashboards, a job that reads alert state, or a provisioning tool that deploys resources, needs credentials that do not belong to a single engineer. A service account is the Grafana identity meant for that job. It is attached to an organization, it holds a role, and it authenticates with one or more tokens that a script or pipeline presents on each API call. Because the account is not a person, it keeps working when someone changes teams, and its actions show up in audit records under the account name rather than an individual's login. Use one service account per automation purpose and per organization, so that a leaked token exposes only the access that one job needed.

Token behavior is version-specific, so this section will not state exact role names, default expiry or token limits. Confirm those in the release you run, including whether tokens can be given an expiry, what the maximum lifetime is, and whether the minimal role in your version is the one named None. Plan for multiple tokens per account. Two active tokens let you create a replacement, move the pipeline to it, and then revoke the old one without an outage. Record which pipeline uses which token so that revocation is a planned change rather than a search through configuration files.

This section also does not cover how users sign in, how roles are mapped from an identity provider, or how Enterprise features such as SCIM provisioning change who can manage accounts. Those topics belong to the authentication sections of this page. Before you write automation, decide who owns each service account, how tokens are stored in your secrets system, how long a token may live, and how you will confirm that a token has been used only by the job it was issued for. The Grafana documentation for each release, linked from the upgrade guidance, is the right place to confirm the details before you build.

Which credential fits each non-human caller

This table compares four ways to give scripts, pipelines and tools access to Grafana, plus the ownership question for each. Read it by first deciding who should own the access, then checking what happens to the automation if that person changes roles. For most shared automation, a service account token owned by a team is the safer default.

Credential	Suits	Who owns it	What breaks when the creator leaves
Service account token	CI pipelines, scheduled jobs and integrations that call the Grafana API	The team that runs the automation, recorded on the service account	Little, if the service account and its token belong to a team. Rotation still needs a named contact.
Personal user token	One-off local scripts and short tests by a single engineer	The individual user	Scripts fail once the user is deactivated or their access is removed. Tokens may carry that person's permissions.
Provisioning files	Data sources, dashboards and alerting resources defined in YAML or JSON and loaded at startup	Whoever maintains the config repository and deployment	Nothing, provided the files are in version control. Changes need a redeploy or restart to load.
Terraform	Declarative management of Grafana resources as code, with state kept by the platform team	The platform team that holds the state and the provider credential	The provider credential breaks if it was a personal token. State access must also survive the departure.
Git Sync	Keeping dashboards and related resources in a Git repository as the source of truth	Repository maintainers and the team that configured the sync	Sync stops if the repository access token or the account behind it is removed. Check ownership of that link.

Decisions to make before creating the first token

Five decisions shape how much damage a leaked token can do and how much work it takes to rotate one. Settle them together before the first service account exists, because each one limits or multiplies the others. Confirm the defaults and available role names in your own Grafana version before you write them into a runbook.

One account per organization or environment

Decide whether a service account serves one Grafana organization, or whether you create separate accounts for development, staging and production. A service account is scoped to the organization where it is created, so a multi-org instance needs an account in each org a script touches. Shared accounts across environments mean a token leaked from staging can read production dashboards. Confirm how your version lists service accounts per organization before you map ownership.

Role and the None role

Give each account the least role its job needs. The None role carries minimal permissions, so a provisioning script that only reads one folder should start there and receive explicit grants, rather than a broad Editor or Admin role. Reserve Admin for accounts that truly manage users or data sources. Check the exact role names and permission set in your version, since permissions for dashboards, folders and alerting have changed across releases.

Token expiry limits

Set a maximum lifetime for every token at creation time. Short expiry limits blast radius, because a stolen token stops working on its own, but they add renewal work for long-running pipelines. Long-lived tokens for nightly jobs are the most common source of forgotten credentials. Confirm in your version whether the expiry limit is enforced by default, whether it can be set per organization, and what happens to running jobs when a token expires.

Tokens per account for rotation

Decide how many tokens each account holds at once. Two tokens let you add a new credential, move the pipeline over and then revoke the old one without downtime. A single token forces a simultaneous cut-over, which tends to be skipped under pressure. More than two tokens per account add tracking effort without much gain. Confirm the per-account token limit in your version, and whether you can see the last-used time for each token.

Who approves new accounts

Name the person or team who approves each new service account, its role and its token, and record the owner in the account name or description. Without an owner, accounts outlive the pipelines that created them and nobody can say which job uses which token. A lightweight request form with the purpose, target dashboards and expiry date is usually enough. Confirm who holds Grafana server admin rights, since those users can create accounts without a second review.

Creating a service account and verifying its access

This sequence gives a script, pipeline or provisioning tool its own scoped identity in one Grafana organization, with a token that expires and a verified record of what it can and cannot do. Each step ends with a check so the result is confirmed before the credential goes into production.

Name the consumer and its purpose
Before opening Grafana, the platform owner writes down which system will use the credential, what it does (for example, reading dashboards for a status report, or provisioning alert rules from a Git pipeline), and which organization it must reach. A name such as the consuming system and its function makes later audits readable. The step is done when the owner has a one-line purpose statement and a named technical contact who will rotate the token. Without a named contact, nobody is accountable when the token expires or the pipeline breaks.
Create the service account in the target organization
An administrator creates the service account inside the Grafana organization the consumer needs, using the service accounts area of the administration menu. Service accounts belong to one organization, so creating it in the wrong organization is a common mistake that surfaces later as access errors. Confirm the exact menu path and label in the version of the docs you run, since names change between releases. The check is that the account appears in the correct organization's list with the name recorded in step one.
Assign the least role that works
Set the service account's role to the lowest one that lets the consumer do its job, and treat any role above Viewer as a deliberate exception that needs a written reason. Grafana also offers a None role with minimal permissions for accounts that should be able to authenticate but reach almost nothing, which is a useful starting point for a consumer you have not yet mapped. Check the role description in your version of the docs before relying on it. The check is a short table in your change record listing the account, organization and role, approved by someone other than the creator.
Create a token with an expiry date
Add a token to the service account and set an expiry, even if your organization's policy would allow a token without one. Enter the expiry in the form Grafana shows for your version and record the date in your secrets inventory so the rotation is scheduled before it lapses. Create a second token only if you are planning an overlapping rotation, since two tokens for one consumer is the pattern that makes rotation safe. The check is that the token list shows the expiry you set and the token value is visible once, so copy it immediately.
Store the token in the pipeline's secret store
Place the token in the secret store your CI system or provisioning tool uses, such as its encrypted variables or a dedicated secrets manager, and reference it by name from the job. Do not paste it into pipeline definitions, shell history, dashboards or chat. Restrict who can read the secret to the jobs that need it. The check is that a pipeline run can read the variable by name while a manual run from an unauthorized user cannot, and that the token value does not appear in job logs when the job prints its environment.
Test a read request with the token
From the consuming environment, make one read-only API call to an endpoint the consumer actually needs, such as listing dashboards or data sources in the target organization. Use the token from the secret store, not a copy typed by hand. Look up the exact endpoint path in the API reference for your Grafana version before running the call. The check is an HTTP success response containing the expected data, and a record of the request in the audit or access logs under the service account's name.
Confirm a write is refused
Make one write request the consumer should not be permitted to make, such as creating a dashboard when the role is Viewer, and confirm Grafana refuses it with an authorization error. This proves the role limits the token as intended and not just that the read works. If the write succeeds, stop, revoke the token, and correct the role before the consumer goes live. The check is a refused response and a log entry for the attempt, which you keep with the change record. Repeat the test whenever the role changes.
Record the access and confirm the endpoints in your version
Write down the service account name, organization, role, token expiry, secret location, and the two test results in your change record or configuration repository. Before you close the change, confirm the menu names, role labels and API paths against the documentation for the version you run, because these details change between releases. Ask your Grafana vendor or implementation partner to walk through the steps in your environment if the instance uses a custom authentication setup. The check is a completed record that a second person has reviewed.

How token practice changes by environment

A single development instance usually has one Grafana server, a small number of users and tokens that exist mainly to test dashboards, provisioning files and scripts. Rotation can be looser here because a leaked development token exposes sample data rather than production telemetry, but the habits you build now often carry into production, so keep the discipline visible. Create the service account in the organization it will touch, give it the None role, and set a short expiry even for testing.

Rotation window: Rotate on a fixed schedule you write down, or whenever a developer who held the token leaves the team, instead of waiting for an incident.
Secret distribution: Keep tokens in a local password manager or a developer secrets file excluded from version control, never in a shared notebook or chat channel.
Validation: Run a single read-only API call, such as a request for the current organization, after each new token is issued to confirm its scope.
Cleanup: Delete tokens from experiments you have finished, so stale credentials do not accumulate on the instance.

Before you copy this pattern to production, confirm with your own environment which token expiry limits and role options your Grafana version offers.

How service accounts map to organizations and teams

A Grafana service account belongs to a single organization, so its permissions apply only inside that organization. If your scripts, CI pipelines or provisioning tools need to work across several organizations, plan one service account per organization and one set of tokens for each. Access granted to an account in one organization does not extend to any other, and a token inherits only the role and scope of the account that issued it. Before you design naming and ownership, list every organization a tool must touch and map each one to its own account. This is the step most teams skip, and it is the usual reason a pipeline works in staging but fails when it writes to a second organization.

Team membership is the second boundary. Grafana's authentication documentation lists team sync as a feature available only in Grafana Enterprise and Grafana Cloud, so a self-hosted open-source instance cannot automatically place a service account into teams from an identity provider group. If your automation depends on team-based folder or dashboard permissions, assign the service account to those teams directly, or grant permissions at the folder level, and document each assignment so it can be reviewed. Do not assume a team-based design will carry over from a sibling identity setup without checking the feature list for your edition.

Confirm two things before you build. First, check which edition and license you run and which identity and provisioning features it includes, using the Grafana authentication documentation and your Grafana Labs agreement, rather than relying on this summary. Second, record for each service account its organization, its role, its team or folder grants and the owner who answers for it. An illustrative example: a reporting pipeline that reads two organizations needs two accounts, two token sets and two entries in your access register, even though both use the same script.

Protecting tokens in CI, provisioning and logs

A service account token is a standing credential that works for any script or pipeline holding it. The controls below keep tokens out of places they can be copied from, limit who can read them, and separate reading from changing Grafana.

Keep tokens out of repositories and images

Tokens committed to a Git repository, baked into a container image or written into a Helm values file remain readable by everyone with access to that history or registry layer. Inject tokens at runtime from your CI secret store or a secrets manager, and scan commits and images for token patterns before they are pushed. Check whether your provisioning files reference tokens through environment variables rather than literal values. Rotate any token that has ever appeared in a repository, even if the commit was later removed.

Restrict which runners and jobs read tokens

A token stored as a CI variable is available to any job that can access that variable, including jobs on forks, merge requests from outside the team, or shared runners used by other projects. Scope each Grafana token to the protected branches and environments that deploy dashboards or alert rules. Confirm with your CI platform whether masked and protected variables behave as you expect for your runner type. Use a separate token for each pipeline so that revoking one does not break the others.

Keep tokens out of URLs and logs

A token passed as a query parameter can appear in reverse proxy access logs, load balancer logs, browser history and monitoring tools that record request URLs. Send tokens only in the Authorization header, and configure proxies and log pipelines to drop or mask that header. Review script output, debug flags and error traces, which often echo full request details. Ask whoever runs your log platform which fields are retained and for how long.

Separate read and write accounts

A pipeline that only reads dashboards for a report should not hold a token that can edit folders, data sources or alert rules. Create one service account for reading and another for provisioning, and assign each the lowest role that does the job. Use the None role as the starting point for new service accounts, then add permissions explicitly. Review these assignments whenever a pipeline changes its purpose.

Harden the Grafana endpoints that leak tokens

The Grafana security hardening guidance recommends secure and SameSite cookies, requiring authentication for the metrics endpoint and hiding the version from unauthenticated users. These settings reduce what an outsider learns about your instance and how a stolen session or scrape request could be used. Verify each setting in your own configuration file and test that your monitoring scraper still authenticates. Treat the version as information that helps attackers choose an exploit.

What teams ask before creating service accounts and tokens

What does it cost to set up Grafana service accounts and API tokens?

The cost is mostly the time of the people doing the work, and it splits into one-time setup and recurring upkeep. One-time work covers mapping which scripts, CI pipelines and provisioning tools need access, creating a service account per organization, choosing the role for each, and setting token expiry. Recurring work covers rotation, reviewing token use and retiring accounts when pipelines change. Your internal platform team is paid for its own hours either way. A partner quote follows from a written scope that lists the number of organizations, pipelines and tools in scope. Ask for the one-time and recurring parts to be priced separately so you can see what you will keep paying for after go-live.

How long does it take to set up service accounts and token rotation?

Duration depends on how many Grafana organizations exist, how many automated consumers need access, and whether those consumers already store credentials in a secrets manager. Work goes faster when each consumer has a clear owner and a documented purpose, and slower when credentials are embedded in scripts or shared between pipelines. Provisioning as code can shorten the work because service accounts and their settings are then defined in files and reviewed like any other change. Ask the partner for a timeline that depends on a named list of consumers and organizations, and confirm which of those items your team must finish before the build starts.

What does our team need to provide before the work starts?

You need to supply a current inventory of everything that calls the Grafana API today, including CI jobs, cron scripts, provisioning tools and monitoring integrations. For each one, record which organization it writes to, what it does (reads dashboards, pushes dashboards, manages data sources or alerts) and who owns it. You also need access to the Grafana instance with admin rights, a decision on where tokens will be stored, and a named contact who can approve changes to pipelines. Missing ownership information is the most common reason this work slows down, so ask for an inventory template in the written scope.

Can our own team set up service accounts and tokens without a partner?

Yes, a team with Grafana administration experience can create service accounts, assign roles and issue tokens using the Grafana interface or API. The harder parts are the inventory, the decision on which role each consumer needs, and changing pipelines without breaking them. Teams often handle the basic setup themselves and bring in a partner for the design of organization boundaries, the rotation procedure and the audit approach, or for hardening the surrounding stack. Confirm your Grafana edition and version before you plan, because the features available to you determine what the design can rely on.

How do we rotate Grafana API tokens without causing an outage?

Use more than one token per service account so a new token can be created and deployed before the old one is revoked. The standard sequence is to issue a second token, update the secret store and the consumer configuration, confirm that the consumer authenticates with the new token, and only then revoke the old one. Set an expiry on every token so rotation happens on a schedule rather than only after an incident. Test the sequence in a non-production Grafana instance first, and make sure each pipeline has a documented owner who can run the change during a planned window.

What should we ask a partner to include in a written scope?

Ask for a scope that names each Grafana instance, organization and consumer in the work, along with the role each service account will hold. It should state the token expiry policy, the storage location for secrets, the rotation procedure and who runs it, and how token use will be recorded and reviewed. The scope should list the deliverables in writing, such as the account inventory, configuration files, runbook and handover session, and it should say what is excluded. Ask how changes after go-live are handled, whether through a retainer or a new scope, and confirm which items depend on your Grafana edition.

How do we audit what our service accounts and tokens actually do?

Start by confirming which audit and usage records your Grafana edition and version expose for API activity, since this varies and should be checked against the current Grafana documentation for your release. Where native records are limited, forward Grafana logs to a central log platform and set retention to match your policy. Map each token to a single consumer so that activity can be attributed to a pipeline and an owner. Review activity on a regular schedule, flag tokens that have not been used, and remove service accounts whose consumers no longer exist.

What happens if a service account token is exposed?

Revoke the exposed token first, then issue a replacement from the same service account and update the consumer that used it. Because each consumer has its own account and token, the blast radius stays limited to the permissions that account holds. Review what the token could have done in the period it was exposed, using the activity records you have, and document the response. Keep the service account role at the minimum the consumer needs, since a narrow role is what limits the damage. Include this procedure in the runbook so the response is not improvised.

Limits to confirm in your environment

Grafana's service account and token behavior depends on the version you run, the edition you license and how your instance is deployed. The items below are the questions to answer from current Grafana documentation or your own test instance before you write a token policy or an automation design.

Which role names and permissions apply

Confirm the exact role names available for service accounts in your version, including the None role, and list the permissions each one grants on dashboards, data sources, alerting and administration. Role sets have changed between releases, so a role that looked minimal in an older guide may carry more rights than you expect. Test each role with a throwaway service account and record what it can and cannot call.

Default and maximum token expiry

Confirm whether new tokens expire by default, what the default lifetime is, and whether an administrator can set a maximum lifetime that users cannot exceed. A token with no expiry stays valid until someone revokes it, which makes rotation depend entirely on process. Ask who sets the expiry limit, where it is configured and whether existing tokens are affected when the limit changes.

Scoping tokens beyond the role

Confirm whether a token can be limited to specific folders, data sources or actions beyond the role assigned to its service account. If scoping is only at the role level, one service account per pipeline is the practical boundary. Also confirm whether a token can be restricted by source address or other attributes, because those controls reduce the value of a leaked credential.

Audit records of token use

Confirm how Grafana records requests made with a service account token, which events are logged, and where the records go. Check whether the token name or ID appears in each record, how long your logging backend keeps them and whether your audit tooling can filter by service account. Without this, you cannot tell which pipeline made a change or whether a token was used after it should have been retired.

Token behavior across HA nodes

Confirm that a token created on one node is accepted by every node behind your load balancer, and that revoking or rotating a token takes effect across the cluster within a time you can accept. Your high availability setup uses a shared database, so test a rotation while requests hit each node. Record any delay between revocation and rejection, and check that in-flight jobs fail cleanly rather than retrying with the old value.

Service accounts in as-code tools

Confirm whether your provisioning method, such as file-based provisioning, Terraform or Git Sync, can create service accounts and tokens, or whether those steps must be done in the UI or API. Check whether a re-run of the same code creates duplicate accounts or tokens, and where the generated token value is stored. Decide early whether secrets come from your vault or from the tool's state, since state files often contain plain-text values.

How DeployOpen scopes and supports Grafana access for automation

DeployOpen plans, implements, documents and supports self-hosted Grafana inside your own infrastructure, including the service accounts and tokens that scripts, CI pipelines and provisioning tools use. Engagements are fixed-scope, with scope and deliverables agreed in writing before work starts, and ongoing support is available as a retainer.

How we scope

Inventory every script, pipeline and provisioning tool that calls the Grafana API and the permissions each one needs.
Agree which service accounts sit in each organization and which role each account receives, including the None role for read-free tasks.
Set token expiry limits, rotation windows and the number of tokens per account in the written scope before work starts.
Confirm the Grafana version, database backend and deployment method, since token handling depends on the environment.

How we build

Create service accounts per organization with the minimum role each automation needs, recorded in version-controlled configuration.
Issue multiple tokens per account so one can be rotated while another remains active, and test the switchover in a non-production instance.
Wire provisioning of data sources, dashboards and alerting resources to the service accounts using Grafana's file-based provisioning.
Verify that each token reaches only the endpoints its job requires, and that failed or expired token calls produce clear errors.

How we hand over

Document each service account, its owner, its organization, its role and the systems that hold its tokens.
Provide a rotation runbook covering token creation, secret storage updates, cutover and revocation of old tokens.
Describe how to review token last-used data and to act on accounts that have gone unused or drifted from their intended role.
Walk your platform and security teams through the setup and record the decisions made during the build.

How we support

Offer a retainer for ongoing token rotation, role reviews and upgrades when Grafana releases change API behavior.
Re-test service account permissions after each Grafana upgrade, since minor and patch releases can change access behavior.
Review audit evidence of automation access with your compliance and security leads on the schedule agreed in the retainer.
Ask any partner to confirm response scope, hours and change handling in writing before you sign.