Administration on Grafana Labs

Back up Grafana

Mon, 16 Mar 2026 19:38:33 +0000

Back up Grafana

This topic explains how to back up a local Grafana deployment, including configuration, plugin data, and the Grafana database.

Back up the Grafana configuration file

Copy Grafana configuration files that you might have modified in your Grafana deployment to a backup directory.

The Grafana configuration files are located in the following directories:

Default configuration: $WORKING_DIR/defaults.ini (Don’t change this file)
Custom configuration: $WORKING_DIR/custom.ini

For more information on where to find configuration files, refer to Configuration file location.

Note
If you installed Grafana using the deb or rpm packages, then your configuration file is located at /etc/grafana/grafana.ini. This path is specified in the Grafana init.d script using --config file parameter.

Back up plugin data

Installing plugins in Grafana creates a folder for each plugin with its associated files and data. Copy all files and folders recursively from this location to your backup repository.

The Grafana plugin files are located in the following directories:

Default location for plugins in a binary or source installation: $WORKING_DIR/data/plugins
Default location for plugins in a deb or rpm package: /var/lib/grafana/plugins. This path is specified in the Grafana init.d script using --config file parameter.

Back up the Grafana database

We recommend that you back up your Grafana database so that you can roll back to a previous version, if required.

SQLite

The default Grafana database is SQLite, which stores its data in a single file on disk. To back up this file, copy it to your backup repository.

Note
To ensure data integrity, shut down your Grafana service before backing up the SQLite database.

The SQLite database file is located in one of the following directories:

Default location for SQLite data in a binary or source installation: $WORKING_DIR/data/grafana.db
Default location for SQLite data in a deb or rpm package: /var/lib/grafana/grafana.db. This path is specified in the Grafana init.d script using --config file parameter.

MySQL

To back up or restore a MySQL Grafana database, run the following commands:

backup:
> mysqldump -u root -p[root_password] [grafana] > grafana_backup.sql

restore:
> mysql -u root -p grafana < grafana_backup.sql

Postgres

To back up or restore a Postgres Grafana database, run the following commands:

backup:
> pg_dump grafana > grafana_backup

restore:
> psql grafana < grafana_backup

Data source management

Mon, 16 Mar 2026 19:38:33 +0000

Data source management

Grafana supports many different storage backends for your time series data (data source). Refer to data sources for more information about using data sources in Grafana. Only users with the organization admin role can add data sources.

For links to data source-specific documentation, see Data sources.

Data source permissions

You can configure data source permissions to allow or deny certain users the ability to query, edit, or administrate a data source. Each data source’s configuration includes a Permissions tab where you can restrict data source permissions to specific users, service accounts, teams, or roles.

The query permission allows users to query the data source.
The edit permission allows users to query the data source, edit the data source’s configuration and delete the data source.
The admin permission allows users to query and edit the data source, change permissions on the data source and enable or disable query caching for the data source.

Note
Available in Grafana Enterprise and Grafana Cloud.

By default, data sources in an organization can be queried by any user in that organization. For example, a user with the Viewer role can issue any possible query to a data source, not just queries that exist on dashboards to which they have access. Additionally, by default, data sources can be edited by the user who created the data source, as well as users with the Admin role.

Assign data source permissions to users, service accounts, teams, or roles

You can assign data source permissions to users, service accounts, teams, and roles which will allow access to query, edit, or administrate the data source.

Click Connections in the left-side menu.
Under Your connections, click Data sources.
Select the data source to which you want to assign permissions.
On the Permissions tab, click Add a permission.
Select User, Service Account, Team, or Role.
Select the entity for which you want to modify permissions.
Select the Query, Edit, or Admin permission.
Click Save.

Edit data source permissions for users, service accounts, teams, or roles

Click Connections in the left-side menu.
Under Your connections, click Data sources.
Select the data source for which you want to edit permissions.
On the Permissions tab, find the User, Service Account, Team, or Role permission you want to update.
Select a different option in the Permission dropdown.

Remove data source permissions for users, service accounts, teams, or roles

Click Connections in the left-side menu.
Under Your connections, click Data sources.
Select the data source from which you want to remove permissions.
On the Permissions tab, find the User, Service Account, Team, or Role permission you want to remove.
Click the X next to the permission.

Query and resource caching

When you enable query and resource caching, Grafana temporarily stores the results of data source queries and resource requests. When you or another user submit the same query or resource request again, the results will come back from the cache instead of from the data source.

When using Grafana, a query pertains to a request for data frames to be modified or displayed. A resource relates to any HTTP requests made by a plugin, such as the Amazon Timestream plugin requesting a list of available databases from AWS. For more information on data source queries and resources, please see the developers page on backend plugins.

The caching feature works for all backend data sources. You can enable the cache globally in Grafana’s configuration, and configure a cache duration (also called Time to Live, or TTL) for each data source individually.

Note
Available in Grafana Enterprise and Grafana Cloud.

The following cache backend options are available: in-memory, Redis, and Memcached.

Note
Storing cached queries in-memory can increase Grafana’s memory footprint. In production environments, a Redis or Memcached backend is highly recommended.

When a panel queries a data source with cached data, it will either fetch fresh data or use cached data depending on the panel’s interval. The interval is used to round the query time range to a nearby cached time range, increasing the likelihood of cache hits. Therefore, wider panels and dashboards with shorter time ranges fetch new data more often than narrower panels and dashboards with longer time ranges.

A panel’s interval is visible in the query options. It is calculated as follows: time range / max data points. Max data points are calculated based on the width of the panel. For example, a wide panel with 1000 data points on a dashboard with a time range of last 7 days will retrieve fresh data every 10 minutes: 7d / 1000 = 10m. In this example, cached data for this panel will be served for up to 10 minutes before Grafana needs to query the data source again for new data.

You can configure a panel to retrieve data more often by increasing the Max data points setting in the panel’s query options.

Caching benefits

By reducing the number of queries and requests sent to data sources, caching can provide the following benefits:

Faster dashboard load times, especially for popular dashboards.
Reduced API costs.
Reduced likelihood that APIs will rate-limit or throttle requests.

Data sources that work with query caching

Query caching works for Grafana’s built-in data sources, and backend data source plugins that extend the DataSourceWithBackend class in the plugins SDK.

To verify that a data source works with query caching, follow the instructions below to Enable and Configure query caching. If caching is enabled in Grafana but the Caching tab is not visible for the given data source, then query caching is not available for that data source.

Note
Some data sources, such as Elasticsearch, Prometheus, and Loki, cache queries themselves, so Grafana query caching does not significantly improve performance. However, resource caching may help. See the developers page on plugin resources for details.

Enable and configure query caching

You must be an Org admin or Grafana admin to enable query caching for a data source. For more information on Grafana roles and permissions, refer to About users and permissions.

By default, data source queries are not cached. To enable query caching for a single data source:

Click Connections in the left-side menu.
Under Your Connections, click Data sources.
In the data source list, click the data source that you want to turn on caching for.
Go to the Cache tab.
Click Enable.
(Optional) Choose custom TTLs for the data source’s queries and resources caching. If you skip this step, then Grafana uses the default TTL.

You can optionally override a data source’s configured TTL for individual dashboard panels. This can be useful when you have queries whose results change more or less often than the configured TTL. In the Edit Panel view, select the caching-enabled data source, expand the Query options, and enter your the TTL in milliseconds.

Note
If query caching is enabled and the Cache tab is not visible in a data source’s settings, then query caching is not available for that data source.

To configure global settings for query caching, refer to the caching section of Configure Grafana Enterprise.

Disable query caching

To disable query caching for a single data source:

Click Connections in the left-side menu.
Under Your Connections, click Data sources.
In the data source list, click the data source that you want to turn off caching for.
On the Cache tab, click Disable.

To disable query caching for an entire Grafana instance, set the enabled flag to false in the caching section of Configure Grafana Enterprise. You will no longer see the Cache tab on any data sources, and no data source queries will be cached.

Clear cache

If you experience performance issues or repeated queries become slower to execute, consider clearing your cache.

Note
This action impacts all cache-enabled data sources. If you are using Memcached, the system clears all data from the Memcached instance.

Click Connections in the left-side menu.
Under Your Connections, click Data sources.
In the data source list, click the data source that you want to clear the cache for.
In the Cache tab, click Clear cache.

Sending a request without cache

If a data source query request contains an X-Cache-Skip header, then Grafana skips the caching middleware, and does not search the cache for a response. This can be particularly useful when debugging data source queries using cURL.

Grafana Teams

Mon, 16 Mar 2026 19:38:33 +0000

Grafana Teams

Grafana Teams makes it easy to organize and administer groups of users in your enterprise. Teams allows you to grant permissions to a group of users instead of granting permissions to individual users one at a time.

Teams are useful in a wide variety of scenarios, such as when onboarding new colleagues or needing access to reports on secure financial data. When you add a user to a team, they get access to all resources assigned to that team.

Teams concepts

A Grafana Team is a group of users within an organization that have common permissions, including access to dashboards and data sources, and those permissions apply to all members of that team. For example, instead of assigning six users access to the same dashboard, you can create a team that consists of those users and assign dashboard permissions to the team. A user can belong to multiple teams.

A Team grants permissions to a wide variety of resources including:

dashboards
data sources
folders
alerts
reports
cloud access policies
annotations
playlists

Note
All members of a Grafana Team have the same exact permissions. A single Team can’t have members with different access levels to resources shared within that Team.

A user can be a Member or an Administrator for a given Team. Members of a Team inherit permissions from the team, but they don’t have team administrator privileges, and can’t edit the team itself. Team Administrators can add members to a team and update its settings, such as the team name, team member’s team roles, UI preferences, and home dashboard.

There are two types of Teams, isolated or collaborative. Isolated teams can only see their own resources. They can’t see other team’s resources like dashboards, data, or alerts. Collaborative teams have access to other team’s resources.

For information about how to optimize Teams, refer to How to best organize your teams and resources in Grafana.

Manage organizations

Mon, 16 Mar 2026 19:38:33 +0000

Manage organizations

This topic describes what organizations are, and how to create, edit, and delete them.

About organizations

An organization is an entity that helps you isolate users and resources such as dashboards, annotations, and data sources from each other. Their purpose is to provide completely separate experiences, which look like multiple instances of Grafana, within a single instance. Multiple organizations are easier and cheaper to manage than multiple instances of Grafana.

Users, configuration settings, and Grafana Enterprise licenses are shared between organizations. Other resources, like dashboards, data sources, annotations, folders, Teams, and Alerts, are isolated within each organization and cannot be easily shared with another organization.

The following table summarizes the resources you can share and/or isolate using organizations.

Resource	Mode
Users	Share or isolate
Folders	Isolate only
Dashboards	Isolate only
Data sources	Isolate only
Alerts	Isolate only
Notification channels	Isolate only
Annotations	Isolate only
Reports	Isolate only
API keys	Isolate only
Authentication providers	Share only
Configuration settings	Share only
Licenses	Share

The member of one organization cannot view dashboards assigned to another organization. However, a user can belong to multiple organizations.

Grafana Server Administrators are responsible for creating organizations. For more information about the Grafana Server Administrator role, refer to Grafana server administrators.

View a list of organizations

Complete this task when you want to view a list of existing organizations.

Before you begin

Ensure that you have Grafana Server Administrator permissions

To view a list of organizations:

Sign in to Grafana as a server administrator.
Click Administration in the left-side menu, General, and then Organizations.

Create an organization

Create an organization when you want to isolate dashboards and other resources from each other.

Before you begin

Ensure that you have Grafana Server Administrator permissions

To create an organization:

Sign in to Grafana as a server administrator.
Click Administration in the left-side menu, General, and then Organizations.
Click + New org.
Enter the name of the new organization and click Create.

Grafana creates the organization, adds you as the organization administrator, and opens the Default preferences page.
In the Preferences section, select a home dashboard, time zone, and week start.

For more information about preferences, refer to Preferences.

For more information about adding users to an organization, refer to Add a user to an organization.

Delete an organization

This action permanently removes an organization from your Grafana server.

Warning
Deleting the organization also deletes all teams and dashboards associated the organization.

Before you begin

Ensure that you have Grafana Server Administrator permissions
Because the delete action removes all teams and dashboards associated with the organization, ensure that the users who rely on the organization dashboards are aware of the change

To delete an organization:

Sign in to Grafana as a server administrator.
Click Administration in the left-side menu, General, and then Organizations.
Click the red X next to the organization that you want to delete.
Click Delete.

Edit an organization

Edit an organization when you want to change its name.

Before you begin

Ensure that you have Grafana Server Administrator permissions

To edit an organization:

Sign in to Grafana as a server administrator.
Click Administration in the left-side menu, General, and then Organizations.
Click the organization you want to edit.
Update the organization name and click Update.

User management

Mon, 16 Mar 2026 19:38:33 +0000

User management

A user is defined as any individual who can log in to Grafana. Each user is associated with a role that includes permissions. Permissions determine the tasks a user can perform in the system. For example, the Admin role includes permissions for an administrator to create and delete users.

Watch the following video to learn how to manage users and permissions in Grafana OSS and Grafana Cloud:

The following topics describe how to use permissions to control user access to data sources, dashboards, users, and teams.

Recorded queries

Mon, 16 Mar 2026 19:38:33 +0000

Recorded queries

Recorded queries allow you to see trends over time by taking a snapshot of a data point on a set interval. This can give you insight into historic trends.

For our plugins that do not return time series, it might be useful to plot historical data. For example, you might want to query ServiceNow to see a history of request response times but it can only return current point-in-time metrics.

Note
Available in Grafana Enterprise and Grafana Cloud.

How recorded queries work

Note
An administrator must configure a Prometheus data source and associate it with a Remote write target before recorded queries can be used.

Recorded queries only work with backend data source plugins. Refer to Backend data source plugin for more information about backend data source plugins. You can recorded four types of queries:

single row and column - A query that returns a single row and column.
row count - A query that returns meaningful rows to be counted.
expression - Any expression. To learn more about creating and using expressions, see Write expression queries.
dataplane numeric - A query that returns dataplane numeric kind data.

After a recorded query is created or enabled, it immediately creates a snapshot and continues to create snapshots at the set interval. The recorded query stops taking snapshots when it is disabled, deleted, or when Grafana is not running. Data points are gathered in the backend by running the recorded query and forwarding each result to a remote-write enabled Prometheus instance.

Using a recorded query

To use a recorded query, create one and add it to a dashboard. After that, it can be managed in Preferences from the Recorded queries tab.

Create a recorded query

Find/create a query you want to record on a dashboard in an edit panel. The query must only return one row and column. If it returns more, you can still record the number of results returned using the “count” option.
- The query’s data source must be a backend data source.
- Expressions can be used to aggregate data from a time series query. Refer to Write expression queries to learn more about creating and using expressions.
Click the record query button located in the top right of the query editor.
Enter recorded query information. All fields are required unless otherwise indicated.
- Name - Name of the recorded query.
- Description - (optional) Describe the recorded query as you want it to appear in the recorded query list.
- Interval - The interval on which the snapshot will be taken. The interval starts when you create the recorded query and will stop if you pause or delete the recorded query. Refer to Managing recorded queries for more information on pausing and deleting recorded queries.
- Range - The relative time range of the query. If you select a range of 30m and an interval of 1h the query will take a snapshot every hour of the past 30 minutes.
- Count query results - If you want to count the rows returned from your query toggle this option on. If this option is off, your query must return one row with one value.
Test your recorded query by clicking the test recorded query button.
Click Start recording query to start recording your query.

Add a recorded query

You can add existing recorded queries to panels in a dashboard. For each recorded query that you add, a Prometheus query is created: generated_recorded_query_name{id="generated_id", name="recorded query name"}. The created query from Prometheus returns all the recorded query’s gathered snapshots.

Navigate to a panel in a dashboard where you wish to add a recorded query.
Click the + Recorded query button located below the queries.
If you want to filter recorded queries by data source, select a data source from the filter by data source drop down menu.
Click the Add button on your recorded query to add it to the panel.

After adding your recorded query to the panel, the panel data source will become -- Mixed --. Your recorded query is represented by a Prometheus query with a name label matching your recorded query name. Refer to Prometheus to learn more about the Prometheus data source.

If after adding a recorded query, a query with a -- Mixed -- data source instead of Prometheus data source appears, this could mean that a Prometheus remote write target was not set up for recorded queries. Refer to Remote write target to set up a remote write point.

Manage recorded queries

Recorded queries can be paused/activated and deleted from the Recorded queries tab in Preferences. Deleting a recorded query will remove it from Grafana, but the information that was gathered in Prometheus will still be there. Pausing a recorded query will no longer gather new data points until it is resumed.

Remote write target

The remote write target is the Prometheus data source that recorded query data points are written to. You will need a Prometheus with remote write enabled and you will need to create a data source for this Prometheus.

The remote write target can be edited by clicking Edit Remote Write Target in the upper right on the Recorded Queries tab in Preferences. Select the Prometheus data source that has remote write enabled and enter the remote write path.

Roles and permissions

Mon, 16 Mar 2026 19:38:33 +0000

Roles and permissions

A user is any individual who can log in to Grafana. Each user is associated with a role that includes permissions. Permissions determine the tasks a user can perform in the system. For example, the Admin role includes permissions for an administrator to create and delete users.

You can assign a user one of three types of permissions:

Grafana server administrator permissions: Manage Grafana server-wide settings and resources
Organization permissions: Manage access to dashboards, alerts, plugins, teams, playlists, and other resources for an entire organization. The available roles are Viewer, Editor, and Admin.
Dashboard and folder permission: Manage access to dashboards and folders

Note
If you are running Grafana Enterprise, you can also control access to data sources and use role-based access control to grant user access to read and write permissions to specific Grafana resources. For more information about access control options available with Grafana Enterprise, refer to Grafana Enterprise user permissions features.

Grafana server administrators

A Grafana server administrator manages server-wide settings and access to resources such as organizations, users, and licenses. Grafana includes a default server administrator that you can use to manage all of Grafana, or you can divide that responsibility among other server administrators that you create.

Note
The server administrator role does not mean that the user is also a Grafana organization administrator.

A server administrator can perform the following tasks:

Manage users and permissions
Create, edit, and delete organizations
View server-wide settings defined in the Configuration file
View Grafana server statistics, including total users and active sessions
Upgrade the server to Grafana Enterprise.

Note
The server administrator role does not exist in Grafana Cloud.

To assign or remove server administrator privileges, see Server user management.

Organization users and permissions

All Grafana users belong to at least one organization. An organization is an entity that exists within your instance of Grafana.

Permissions assigned to a user within an organization control the extent to which the user has access to and can update the following organization resources:

dashboards and folders
alerts
playlists
users within that organization
data sources
teams
organization and team settings
plugins
annotations
library panels
API keys

For more information about managing organization users, see User management.

Organization roles

Organization role-based permissions are global, which means that each permission level applies to all Grafana resources within an given organization. For example, an editor can see and update all dashboards in an organization, unless those dashboards have been specifically restricted using dashboard permissions.

Grafana uses the following roles to control user access:

Organization administrator: Has access to all organization resources, including dashboards, users, and teams.
Editor: Can view and edit dashboards, folders, and playlists.
Viewer: Can view dashboards, playlists, and query data sources.
No Basic Role: Has no permissions. Permissions will be added with RBAC as needed.

The following table lists permissions for each role.

Permission	Organization administrator	Editor	Viewer
View dashboards	yes	yes	yes
Add, edit, delete dashboards	yes	yes
Add, edit, delete folders	yes	yes
View playlists	yes	yes	yes
Add, edit, delete playlists	yes	yes
Create library panels	yes	yes
View annotations	yes	yes	yes
Add, edit, delete annotations	yes	yes
Access Explore	yes	yes
Query data sources directly	yes	yes	yes
Add, edit, delete data sources	yes
Add and edit users	yes
Add and edit teams	yes
Change organizations settings	yes
Change team settings	yes
Configure application plugins	yes

Dashboard permissions

When you want to extend a viewer’s ability to edit and save dashboard changes or limit an editor’s permission to modify a dashboard, you can assign permissions to dashboards and folders. For example, you might want a certain viewer to be able to edit a dashboard. While that user can see all dashboards, you can grant them access to update only one of them.

Important: The dashboard permissions you specify override the organization permissions you assign to the user for the selected entity.

You can specify the following permissions to dashboards and folders.

Admin: Can create, edit, or delete a dashboard. Can edit or delete a folder, and create dashboards and subfolders in a folder. Administrators can also change dashboard and folder permissions.
Edit: Can create, edit, or delete a dashboard. Can edit or delete a folder, and create dashboards and subfolders in a folder. Editors cannot change folder or dashboard permissions.
View: Can only view dashboards and folders.

Important: When a user creates a dashboard or a folder they are automatically granted Admin permissions for it.

For more information about assigning dashboard folder permissions, refer to Grant dashboard folder permissions.

For more information about assigning dashboard permissions, refer to Grant dashboard permissions.

Editors with administrator permissions

If you have access to the Grafana server, you can modify the default editor role so that editors can use administrator permissions to manage dashboard folders, dashboards, and teams that they create.

Note
This permission does not allow editors to manage folders, dashboards, and teams that they do not create.

This setting can be used to enable self-organizing teams to administer their own dashboards.

For more information about assigning administrator permissions to editors, refer to Grant editors administrator permissions.

Viewers with dashboard preview and Explore permissions

If you have access to the Grafana server, you can modify the default viewer role so that viewers can:

Edit and preview dashboards, but cannot save their changes or create new dashboards.
Access and use Explore.

Extending the viewer role is useful for public Grafana installations where you want anonymous users to be able to edit panels and queries, but not be able to save or create new dashboards.

For more information about assigning dashboard preview permissions to viewers, refer to Enable viewers to preview dashboards and use Explore.

Teams and permissions

A team is a group of users within an organization that have common dashboard and data source permission needs. For example, instead of assigning five users access to the same dashboard, you can create a team that consists of those users and assign dashboard permissions to the team. A user can belong to multiple teams.

You can assign a team member one of the following permissions:

Member: Includes the user as a member of the team. Members do not have team administrator privileges.
Admin: Administrators have permission to manage various aspects of the team, including team membership, permissions, and settings.

Because teams exist inside an organization, the organization administrator can manage all teams. When the editors_can_admin setting is enabled, editors can create teams and manage teams that they create. For more information about the editors_can_admin setting, refer to Grant editors administrator permissions.

For details on managing teams, see Team management.

Grafana Enterprise user permissions features

While Grafana OSS includes a robust set of permissions and settings that you can use to manage user access to server and organization resources, you might find that you require additional capabilities.

Grafana Enterprise provides the following permissions-related features:

Data source permissions
Role-based access control (RBAC)

Data source permissions

By default, a user can query any data source in an organization, even if the data source is not linked to the user’s dashboards.

Data source permissions enable you to restrict data source query permissions to specific Users, Service Accounts, and Teams. For more information about assigning data source permissions, refer to Data source permissions.

Role-based access control

RBAC provides you a way of granting, changing, and revoking user read and write access to Grafana resources, such as users, reports, and authentication.

For more information about RBAC, refer to Role-based access control.

Learn more

Want to know more? Complete the Create users and teams tutorial to learn how to set up users and teams.

View server statistics and license

Mon, 16 Mar 2026 19:38:33 +0000

View server statistics and license

This setting contains information about tools that Grafana Server Admins can use to learn more about their Grafana servers.

View Grafana server settings

Refer to Role-based access control in Grafana Enterprise to understand how you can control access with RBAC permissions.

If you are a Grafana server administrator, use the Settings tab to view the settings that are applied to your Grafana server via the Configuration file and any environmental variables.

Note: Only Grafana server administrators can access the Server Admin menu. For more information about about administrative permissions, refer to Roles and permissions.

View server settings

Log in to your Grafana server with an account that has the Grafana Admin flag set.
Click Administration in the left-side menu, General, and then Settings.

Available settings

For a full list of server settings, refer to Configuration.

View Grafana server stats

Refer to Role-based access control in Grafana Enterprise to understand how you can control access with RBAC permissions.

If you are a Grafana server admin, then you can view useful statistics about your Grafana server in the Stats & Licensing tab.

Note: Only Grafana server administrators can access the Server Admin menu. For more information about about administrative permissions, refer to Roles and permissions.

View server stats

Log in to your Grafana server with an account that has the Grafana Admin flag set.
Click Administration in the left-side menu, General, and then Stats and license.

Available stats

The following statistics are displayed in the Stats tab:

Total users Note: Total users = Total admins + Total editors + Total viewers
Total admins
Total editors
Total viewers
Active users (seen last 30 days) Note: Active users = Active admins + Active editors + Active viewers
Active admins (seen last 30 days)
Active editors (seen last 30 days)
Active viewers (seen last 30 days)
Active sessions
Total dashboards
Total orgs
Total playlists
Total snapshots
Total dashboard tags
Total starred dashboards
Total alerts

Counting users

If a user belongs to several organizations, then that user is counted once as a user in the highest organization role they are assigned, regardless of how many organizations the user belongs to.

For example, if Sofia is a Viewer in two organizations, an Editor in two organizations, and Admin in three organizations, then she would be reflected in the stats as:

Total users 1
Total admins 1

Grafana Enterprise license

Mon, 16 Mar 2026 19:38:33 +0000

Grafana Enterprise license

When you become a Grafana Enterprise customer, you gain access to Grafana’s premium observability features, including enterprise data source plugins, reporting, and role-based access control. In order to use these enhanced features of Grafana Enterprise, you must purchase and activate a Grafana Enterprise license.

To purchase a license directly from Grafana Labs, Contact a Grafana Labs representative. To activate an Enterprise license purchased from Grafana Labs, refer to Activate an Enterprise license.

You can also purchase a Grafana Enterprise license through the AWS Marketplace. To learn more about activating a license purchased through AWS, refer to Activate a Grafana Enterprise license purchased through AWS Marketplace.

Activate a Grafana Enterprise license purchased through AWS Marketplace

Activate an Enterprise license

Follow these steps to activate your Grafana Enterprise license:

Step 1. Download your license file

To download your Grafana Enterprise license:

Sign in to your Grafana Cloud account.
Go to My Account and select an organization from the drop-down menu at the top left of the page. On the Overview page for each organization, you can see a section for Grafana Enterprise licenses. Click Details next to a license.
At the bottom of the license details page, select Download token to download the license.jwt file that contains your license.

Step 2. Add your license to a Grafana instance

You must install a Grafana Enterprise build to use the enterprise features, which you can download.

Note
If you already use Grafana OSS, you can replace it with the same version of Grafana Enterprise. Ensure that you back up the configuration and database before proceeding. For more information, refer to Back up Grafana.

There is more than one way to add the license to a Grafana instance:

Upload the license file via the Grafana server administrator page

This is the preferred option for single instance installations of Grafana Enterprise.

Sign in as a Grafana server administrator.
Click Administration > General > Stats and license in the side navigation menu.
Click Upload a new token.
Select your license file, and upload it.

Put the `license.jwt` file into the data directory of Grafana

On Linux systems, the data directory is usually at /var/lib/grafana.

You can also configure a custom location for the license file using the grafana.ini setting:

[enterprise]
license_path = /company/secrets/license.jwt

This setting can also be set with an environment variable, which is useful if you’re running Grafana with Docker and have a custom volume where you have placed the license file. In this case, set the environment variable GF_ENTERPRISE_LICENSE_PATH to point to the location of your license file.

Set the content of the license file as a configuration option

You can add a license by pasting the content of the license.jwt to the grafana.ini configuration file:

[enterprise]
license_text = eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0aGlzIjoiaXMiLCJub3QiOiJhIiwidmFsaWQiOiJsaWNlbnNlIn0.bxDzxIoJlYMwiEYKYT_l2s42z0Y30tY-6KKoyz9RuLE

This option can be set using the GF_ENTERPRISE_LICENSE_TEXT environment variable.

Step 3. Ensure that the license file’s root URL matches the root_url configuration option

Update the root_url in your configuration. It should be the URL that users type in their browsers to access the frontend, not the node hostname(s).

This is important, because as part of the validation checks at startup, Grafana compares the license URL to the root_url in your configuration.

In your configuration file:

[server]
root_url = https://grafana.example.com/

Or with an environment variable:

GF_SERVER_ROOT_URL=https://grafana.example.com/

Step 4. Restart Grafana

To finalize the installation of Grafana Enterprise, restart Grafana to enable all Grafana Enterprise features. Refer to restart Grafana for more information.

License expiration

If your license has expired, most of Grafana keeps working as normal. Some enterprise functionality stops or runs with reduced functionality and Grafana displays a banner informing the users that Grafana is running on an expired license. Your Grafana admin needs to upload a new license file to restore full functionality.

Replace your license as soon as possible. Running Grafana Enterprise with an expired license is unsupported and can lead to unexpected consequences.

Update your license

Locate your current license.jwt file. In a standard installation it is stored inside the Grafana data directory, which on a typical Linux installation is in /var/lib/grafana/data. This location might be overridden in the ini file Configuration.
ini
```
[enterprise]
license_path = /path/to/your/license.jwt
```
The configuration file’s location may also be overridden by the GF_ENTERPRISE_LICENSE_PATH environment variable.
Log in to your Grafana Cloud Account and make sure you’re in the correct organization in the dropdown at the top of the page.
Under the Grafana Enterprise section in the menu bar to the left, choose licenses and download the currently valid license with which you want to run Grafana. If you cannot see a valid license on Grafana.com, please contact your account manager at Grafana Labs to renew your subscription.
Replace the current license.jwt-file with the one you’ve just downloaded.
Restart Grafana.

If your license expires

If your Grafana Enterprise license expires, you can expect the following changes in feature behavior.

Data source permissions

Your current data source permissions will keep working as expected, but you’ll be unable to add new data source permissions until the license has been renewed.

LDAP authentication

LDAP synchronization is not affected by an expired license.
Team sync debugging is unavailable.

SAML authentication

SAML authentication is not affected by an expired license.

Role-based access control (RBAC)

Creating, updating and deleting custom roles is not available.
Modifying permissions for custom roles is not available.

Reporting

You’re unable to configure new reports or generate previews.
Existing reports continue to be sent.

Enterprise plugins

Enterprise plugins might stop working.

White labeling

The white labeling feature is turned off, meaning that any white labeling options will not have any effect.

Usage insights

Exporting usage insights logs to Loki will be turned off for licenses expired for more than 7 days.

All the other usage insights features are turned off as soon as the license expires, meaning that you will not be able to see dashboard usage, presence indicators, or use improved search. Grafana continues to collect usage data and you will have access to it as soon as you update your license.

Vault integration

Vault integration is not affected by an expired license.

Auditing

Auditing is not affected by an expired license.

License restrictions

The concurrent session limit remains active for seven days after the expiration date, after which it will be turned off.

The active users limit is turned off immediately.

Settings updates at runtime

Settings updates at runtime are not affected by an expired license.

External users can’t access dashboards shared via email anymore. These dashboards are now private but you can make them public and accessible to everyone if you want to.

Grafana keeps your sharing configurations and restores them after you update your license.

Grafana Enterprise license restrictions

When you become a Grafana Enterprise customer, you receive a license that governs your use of Grafana Enterprise.

Active users limit

Your Grafana license includes a maximum number of active users.

An active user is a user who has signed in to Grafana within the last 30 days. This is a rolling window that is updated daily.
When you reach the maximum number of active users, only currently active users (users who have signed in over the past 30 days) can sign in. When a new user or a previously-inactive user tries to sign in, the user will see an error message indicating that Grafana has reached its license limit.
The user’s role, number of dashboards that a user can view or edit, and the number of organizations that they can access does not affect the active user count.
A license limit banner appears to administrators when Grafana reaches its active user limit; editors and viewers do not see the banner.

Determine the number of active users

To determine the number of active users:

Sign in to Grafana Enterprise as a System Administrator.
Click Administration in the side navigation menu.
Click General.
Click Stats and license.
Review the utilization count on the Utilization panel.

Tiered licensing (deprecated)

A tiered license defines dashboard viewers, and dashboard editors and administrators, as two distinct user types that each have their own user limit.

As of Grafana Enterprise version 9.0, Grafana only counts and enforces the total number of active users in your Grafana instance. For example, if you purchase 150 active users, you can have 20 admins, 70 editors, and 60 viewers, or you can have 150 admins. Grafana will enforce the total number of active users even if you use a license that grants a specific number of admins or editors and a certain number of viewers. This is a more permissive policy than before, which gives you the flexibility to change users’ roles.

If you are running a pre-9.0 version of Grafana Enterprise, please refer to the documentation for that version to learn more about license enforcement in your current version.

Additional license restrictions

Your license is controlled by the following rules:

License expiration date: The license includes an expiration date, which is the date when a license becomes inactive.

As the license expiration date approaches, you will see a banner in Grafana that encourages you to renew. To learn about how to renew your license and what happens in Grafana when a license expires, refer to License expiration.

Grafana License URL: Your license does not work with an instance of Grafana with a different root URL.

The License URL is the complete URL of your Grafana instance, for example https://grafana.your-company.com/. It is defined in the root_url configuration setting.

Concurrent sessions limit: As of Grafana Enterprise 7.5, users can initiate up to three concurrent sessions of Grafana.

The system creates a session when a user signs in to Grafana from a new device, a different browser, or an incognito window. If a user signs in to Grafana from another tab or window within the same browser, only one session is used.

When a user reaches the session limit, the fourth connection succeeds and the longest inactive session is signed out.

Request usage billing

You can request Grafana Labs to activate usage billing which allows an unlimited number of active users. When usage billing is enabled, Grafana does not enforce active user limits or display warning banners. Instead, you are charged for active users that exceed the limit, according to your customer contract.

Usage billing involves a contractual agreement between you and Grafana Labs, and it is only available if Grafana Enterprise is configured to automatically refresh its license token.

Request a change to your license

To increase the number of licensed users within Grafana, extend a license, or change your licensed URL, contact Grafana support or your Grafana Labs account team. They will update your license, which you can activate from within Grafana.

For instructions about how to activate your license after it is updated, refer to Activate an Enterprise license.

Organization preferences

Mon, 16 Mar 2026 19:38:33 +0000

Organization preferences

Grafana preferences are basic settings. They control the Grafana UI theme, home dashboard, time zone, and so on.

Preferences are sometimes confusing because they can be set at four different levels, listed from highest level to lowest:

Server - Affects all users on the Grafana server. Set by a Grafana server admin.
Organization - Affects all users in an organization. Set by an Organization admin.
Team - Affects all users assigned to a team. Set by an Organization Admin or Team Admin. To learn more about these roles, refer to Teams and permissions.
User account - Affects the individual user. Set by the user on their own account.

The lowest level always takes precedence. For example, if a user sets their theme to Light, then their visualization of Grafana displays the light theme. Nothing at any higher level can override that.

If the user is aware of the change and intended it, then that’s great! But if the user is a Server Admin who made the change to their user preferences a long time ago, they might have forgotten they did that. Then, if that Server Admin is trying to change the theme at the server level, they’ll get frustrated as none of their changes have any effect that they can see. (Also, the users on the server might be confused, because they can see the server-level changes!)

Change Grafana name and email

In Grafana, you can change your names and emails associated with groups or accounts in the Settings or Preferences. This topic provides instructions for each task.

Some tasks require certain permissions. For more information about roles, refer to Roles and permissions.

Change organization name

Grafana server administrators and organization administrators can change organization names.

Grafana Server Admin change organization name

Follow these instructions if you are a Grafana Server Admin.

Click Administration in the left-side menu.
Click General.
Click Organizations.
In the organization list, click the name of the organization that you want to change.
In Name, enter the new organization name.
Click Update.

Organization Admin change organization name

If you are an Organization Admin, follow these steps:

Click Administration in the left-side menu.
Click General.
Click Default preferences.
In Organization name, enter the new name.
Click Update organization name.

Change team name or email

Organization administrators and team administrators can change team names and email addresses. To change the team name or email, follow these steps:

Click Administration in the left-side menu, Users and access, and select Team.
In the team list, click the name of the team that you want to change.
Click the Settings tab.
In the Team details section, you can edit the following:
- Name - Edit this field to change the display name associated with the team.
- Email - Edit this field to change the email address associated with the team.
Click Update.

Change user name or email

To learn how to edit your user information, refer to Edit your profile.

Change Grafana UI theme

In Grafana, you can modify the UI theme configured in the Settings or Preferences. Set the UI theme for the server, an organization, a team, or your personal user account using the instructions in this topic.

Some tasks require certain permissions. For more information about roles, refer to Roles and permissions.

Theme options

The theme affects how Grafana displays graphs, menus, other UI elements.

Default

Default is either the dark theme or the theme selected in a higher level. For example, if an Organization administrator set the Light theme, then that is the default for all the teams in that organization.

Dark

Here is an example of the dark theme.

Light

Here is an example of the light theme.

Change server UI theme

As a Grafana server administrator, you can change the default Grafana UI theme for all users who are on the server by setting the default_theme option in the Grafana configuration file.

To see what the current settings are, refer to View server settings.

Change organization UI theme

Organization administrators can change the UI theme for all users in an organization.

Click Administration in the left-side menu.
Click General.
Click Default preferences.
In the Preferences section, select the UI theme.
Click Save.

Change team UI theme

Organization and team administrators can change the UI theme for all users on a team.

Click Administration in the left-side menu, Users and access, and select Teams.
Click the team for which you want to change the UI theme.
Click the Settings tab.
In the Preferences section, select the UI theme.
Click Save.

Change your personal UI theme

You can change the UI theme for your user account. This setting overrides UI theme settings at higher levels.

Click the user icon in the top right corner of the page and select Profile.
In the Preferences section, select the UI theme.
Click Save.

Change the Grafana default timezone

By default, Grafana uses the timezone in your web browser. However, you can override this setting at the server, organization, team, or individual user level. This topic provides instructions for each task.

Some tasks require certain permissions. For more information about roles, refer to Roles and permissions.

Set server timezone

Grafana server administrators can choose a default timezone for all users on the server by setting the default_timezone option in the Grafana configuration file.

Set organization timezone

Organization administrators can choose a default timezone for their organization.

Click Administration in the left-side menu.
Click General.
Click Default preferences.
Click to select an option in the Timezone list. Default is either the browser local timezone or the timezone selected at a higher level.
Click Save.

Set team timezone

Organization administrators and team administrators can choose a default timezone for all users on a team.

Click Administration in the left-side menu, Users and access, and select Teams.
Click the team for which you want to change the timezone.
Click the Settings tab.
Click to select an option in the Timezone list. Default is either the browser local timezone or the timezone selected at a higher level.
Click Save.

Set your personal timezone

You can change the timezone for your user account. This setting overrides timezone settings at higher levels.

Click the user icon in the top right corner of the page and select Profile.
Click to select an option in the Timezone list. Default is either the browser local timezone or the timezone selected at a higher level.
Click Save.

Change the default home dashboard

The home dashboard you set is the one all users will see by default when they log in. Click the Grafana icon or Home in the breadcrumb to return to it. You can set the home dashboard for the server, an organization, a team, or your personal user account. This topic provides instructions for each task.

Some tasks require certain permissions. For more information about roles, refer to Roles and permissions.

Set the home dashboard for the server

Users with the Grafana Server Admin flag on their account or access to the configuration file can define a JSON file to use as the home dashboard for all users on the server.

[Optional] Convert an existing dashboard into a JSON file

Navigate to the page of the dashboard you want to use as the home dashboard.
Click the Share button at the top right of the screen.
In the Export tab, click Save to file. Grafana converts the dashboard to a JSON file and saves it locally.

Use a JSON file as the home dashboard

Save your JSON file somewhere that Grafana can access it. For example, in the Grafana data folder of Grafana.
Update your configuration file to set the path to the JSON file. Refer to default_home_dashboard_path for more information about modifying the Grafana configuration files.

[dashboards]
# Path to the default home dashboard. If this value is empty, then Grafana uses StaticRootPath + "dashboards/home.json"
default_home_dashboard_path = data/main-dashboard.json

Note
On Linux, Grafana uses /usr/share/grafana/public/dashboards/home.json as the default home dashboard location.

Set the home dashboard for your organization

Organization administrators can choose a default home dashboard for their organization.

Navigate to the dashboard you want to set as the home dashboard.
Click the star next to the dashboard title to mark the dashboard as a favorite if it is not already.
Click Administration in the left-side menu.
Click General.
Click Default preferences.
In the Home Dashboard field, select the dashboard that you want to use for your home dashboard. Options include all starred dashboards.
Click Save.

Set home dashboard for your team

Organization administrators and Team Admins can set a default home dashboard for all users on a team.

Navigate to the dashboard you want to set as the home dashboard.
Click the star next to the dashboard title to mark the dashboard as a favorite if it is not already.
Click Administration in the left-side menu, Users and access, and select Teams.
Click the team for which you want to change the home dashboard.
Click the Settings tab.
In the Home Dashboard field, select the dashboard that you want to use for your home dashboard. Options include all starred dashboards.
Click Save.

Set your personal home dashboard

You can choose your own personal home dashboard. This setting overrides all home dashboards set at higher levels.

Navigate to the dashboard you want to set as the home dashboard.
Click the star next to the dashboard title to mark the dashboard as a favorite if it is not already.
Click the user icon in the top right corner of the page and select Profile.
In the Home Dashboard field, select the dashboard that you want to use for your home dashboard. Options include all starred dashboards.
Click Save.

Change Grafana language

Change server language

Grafana server administrators can change the default Grafana UI language for all users on the server by setting the default_language option in the Grafana configuration file.

Change organization language

Organization administrators can change the language for all users in an organization.

Click Administration in the left-side menu.
Click General.
Click Default preferences.
In the Preferences section, select an option in the Language dropdown.
Click Save.

Change team language

Organization and team administrators can set a default language for all users on a team.

Click Administration in the left-side menu, Users and access, and select Teams.
Click the team for which you want to change the language.
Click the Settings tab.
In the Preferences section, select an option in the Language dropdown.
Click Save.

Change your personal language

You can change the language for your user account. This setting overrides language settings at higher levels.

Click the user icon in the top right corner of the page and select Profile.
In the Preferences section, select an option in the Language dropdown.
Click Save.

Plugin management

Mon, 16 Mar 2026 19:38:33 +0000

Plugin management

You can enhance your Grafana experience with plugins, extensions to Grafana beyond the wide range of visualizations and data sources that are built-in.

This guide shows you how to install plugins that are built by Grafana Labs, commercial partners, our community, or plugins that you have built yourself.

Types of plugins

Grafana supports three types of plugins:

Panels - These plugins make it easy to create and add any kind of panel, to show your data, or improve your favorite dashboards.
Data sources - These plugins allow you to pull data from various data sources such as databases, APIs, log files, and so on, and display it in the form of graphs, charts, and dashboards in Grafana.
Apps - These plugins enable the bundling of data sources, panels, dashboards, and Grafana pages into a cohesive experience.

Panel plugins

Add new visualizations to your dashboard with panel plugins, such as the Clock, Mosaic and Variable panels.

Use panel plugins when you want to:

Visualize data returned by data source queries.
Navigate between dashboards.
Control external systems, such as smart home devices.

Data source plugins

Data source plugins add support for new databases, such as Google BigQuery.

Data source plugins communicate with external sources of data and return the data in a format that Grafana understands. By adding a data source plugin, you can immediately use the data in any of your existing dashboards.

Use data source plugins when you want to query data from external or third-party systems.

App plugins

Applications, or app plugins, bundle data sources and panels to provide a cohesive experience, such as the Zabbix app.

Apps can also add custom pages for things like control panels.

Use app plugins when you want an out-of-the-box monitoring experience.

Managing access for app plugins

Customize access to app plugins with RBAC.

By default, the Viewer, Editor and Admin roles have access to all app plugins that their Organization role allows them to access. Access is granted by the fixed:plugins.app:reader role.

Note
To prevent users from seeing an app plugin, refer to these permissions scenarios.

Plugin catalog

The Grafana plugin catalog allows you to browse and manage plugins from within Grafana. Only Grafana server administrators and Organization administrators can access and use the plugin catalog. For more information about Grafana roles and permissions, refer to Roles and permissions.

The following access rules apply depending on the user role:

If you are an Org Admin, you can configure app plugins, but you can’t install, uninstall, or update them.
If you are a Server Admin, you can’t configure app plugins, but you can install, uninstall, or update them.
If you are both Org Admin and Server Admin, you can configure app plugins and also install, uninstall, or update them.

Note
The Grafana plugin catalog is designed to work with a single Grafana server instance only. Support for Grafana clusters is planned for future Grafana releases.

Your browser does not support the video tag.

Video shows the Plugin catalog in a previous version of Grafana.

Note
If required, the Grafana plugin catalog can be disabled using the plugin_admin_enabled flag in the configuration file.

Browse plugins

To browse for available plugins:

While logged into Grafana as an administrator, click Administration > Plugins and data > Plugins in the side menu to view installed and available plugins.
Use the search to filter based on name, keywords, organization and other metadata.
Click the Data sources, Panels, or Applications buttons to filter by plugin type.

Install a plugin

To install a plugin:

In Grafana, click Administration > Plugins and data > Plugins in the side navigation menu to view all plugins.
Browse and find a plugin.
Click the plugin’s logo.
Click Install.

When the update is complete, you’ll see a confirmation message that the installation was successful.

Update a plugin

To update a plugin:

In Grafana, click Administration > Plugins and data > Plugins in the side navigation menu to view all plugins.
Click the Installed filter to show only installed plugins.
Click the plugin’s logo.
Click Update.

When the update is complete, you’ll see a confirmation message that the update was successful.

Uninstall a plugin

To uninstall a plugin:

In Grafana, click Administration > Plugins and data > Plugins in the side navigation menu to view all plugins.
Click the plugin’s logo.
Click the Installed filter to show only installed plugins.
Click Uninstall.

When the update is complete, you’ll see a confirmation message that the uninstall was successful.

Install Grafana plugins

Grafana supports data source, panel, and app plugins.

In a web browser, navigate to the Grafana plugin catalog and find a plugin that you want to install.
Click the plugin, and then click the Installation tab.

Install plugin on Grafana Cloud

On the Installation tab, in the For field, click the name of the Grafana instance on which you want to install the plugin.

Grafana Cloud handles the plugin installation automatically.

If you’re logged in to Grafana Cloud when you add a plugin, log out and then log back in again to use the new plugin.

Install plugin on local Grafana

Follow the instructions on the Install tab. You can either install the plugin with a Grafana CLI command or by downloading and uncompressing a zip file into the Grafana plugins directory. We recommend using Grafana CLI in most instances. The zip option is available if your Grafana server doesn’t have access to the internet.

For more information about Grafana CLI plugin commands, refer to Plugin commands.

Install a packaged plugin

After the user has downloaded the archive containing the plugin assets, they can install it by extracting the archive into their plugin directory. For example:

unzip my-plugin-0.2.0.zip -d YOUR_PLUGIN_DIR/my-plugin

The path to the plugin directory is defined in the configuration file. For more information, refer to Configuration.

Plugin signatures

Plugin signature verification, also known as signing, is a security measure to make sure plugins haven’t been tampered with. Upon loading, Grafana checks to see if a plugin is signed or unsigned when inspecting and verifying its digital signature.

At startup, Grafana verifies the signatures of every plugin in the plugin directory. If a plugin is unsigned, then Grafana neither loads nor starts it. To see the result of this verification for each plugin, navigate to Configuration -> Plugins.

Grafana also writes an error message to the server log:

WARN[05-26|12:00:00] Some plugin scanning errors were found   errors="plugin '<plugin id>' is unsigned, plugin '<plugin id>' has an invalid signature"

If you are a plugin developer and want to know how to sign your plugin, refer to Sign a plugin.

Signature status	Description
Core	Core plugin built into Grafana.
Invalid signature	The plugin has an invalid signature.
Modified signature	The plugin has changed since it was signed. This may indicate malicious intent.
Unsigned	The plugin is not signed.
Signed	The plugin signature was successfully verified.

Plugin signature levels

All plugins are signed under a signature level. The signature level determines how the plugin can be distributed.

Plugin Level	Description
Private	Private plugins are for use on your own Grafana. They may not be distributed to the Grafana community, and are not published in the Grafana catalog.
Community	Community plugins have dependent technologies that are open source and not for profit. Community plugins are published in the official Grafana catalog, and are available to the Grafana community.
Commercial	Commercial plugins have dependent technologies that are closed source or commercially backed. Commercial plugins are published on the official Grafana catalog, and are available to the Grafana community.

Plugin Level

Description

Private

Private plugins are for use on your own Grafana. They may not be distributed to the Grafana community, and are not published in the Grafana catalog.

Community

Community plugins have dependent technologies that are open source and not for profit.

Community plugins are published in the official Grafana catalog, and are available to the Grafana community.

Commercial

Commercial plugins have dependent technologies that are closed source or commercially backed.

Commercial plugins are published on the official Grafana catalog, and are available to the Grafana community.

Allow unsigned plugins

Note
Unsigned plugins are not supported in Grafana Cloud.

We strongly recommend that you don’t run unsigned plugins in your Grafana instance. However, if you’re aware of the risks and you still want to load an unsigned plugin, refer to Configuration.

If you’ve allowed loading of an unsigned plugin, then Grafana writes a warning message to the server log:

WARN[06-01|16:45:59] Running an unsigned plugin   pluginID=<plugin id>

Note
If you’re developing a plugin, then you can enable development mode to allow all unsigned plugins.

Learn more

Provision Grafana

Mon, 16 Mar 2026 19:38:33 +0000

Provision Grafana

In previous versions of Grafana, you could only use the API for provisioning data sources and dashboards. But that required the service to be running before you started creating dashboards and you also needed to set up credentials for the HTTP API. In v5.0 we decided to improve this experience by adding a new active provisioning system that uses config files. This will make GitOps more natural as data sources and dashboards can be defined via files that can be version controlled. We hope to extend this system to later add support for users and orgs as well.

Config File

See Configuration for more information on what you can configure in grafana.ini.

Config File Locations

Default configuration from $WORKING_DIR/conf/defaults.ini
Custom configuration from $WORKING_DIR/conf/custom.ini
The custom configuration file path can be overridden using the --config parameter

Note
If you have installed Grafana using the deb or rpm packages, then your configuration file is located at /etc/grafana/grafana.ini. This path is specified in the Grafana init.d script using --config file parameter.

Using Environment Variables

It is possible to use environment variable interpolation in all 3 provisioning configuration types. Allowed syntax is either $ENV_VAR_NAME or ${ENV_VAR_NAME} and can be used only for values not for keys or bigger parts of the configurations. It is not available in the dashboard’s definition files just the dashboard provisioning configuration. Example:

datasources:
  - name: Graphite
    url: http://localhost:$PORT
    user: $USER
    secureJsonData:
      password: $PASSWORD

If you have a literal $ in your value and want to avoid interpolation, $$ can be used.

Configuration Management Tools

Currently we do not provide any scripts/manifests for configuring Grafana. Rather than spending time learning and creating scripts/manifests for each tool, we think our time is better spent making Grafana easier to provision. Therefore, we heavily rely on the expertise of the community.

Tool	Project
Puppet	https://forge.puppet.com/puppet/grafana
Ansible	https://github.com/grafana/grafana-ansible-collection
Chef	https://github.com/sous-chefs/chef-grafana
Saltstack	https://github.com/salt-formulas/salt-formula-grafana
Jsonnet	https://github.com/grafana/grafonnet-lib/
NixOS	services.grafana.provision module

Data sources

Note
Available in Grafana v5.0 and higher.

You can manage data sources in Grafana by adding YAML configuration files in the provisioning/datasources directory. Each config file can contain a list of datasources to add or update during startup. If the data source already exists, Grafana reconfigures it to match the provisioned configuration file.

The configuration file can also list data sources to automatically delete, called deleteDatasources. Grafana deletes the data sources listed in deleteDatasources before adding or updating those in the datasources list.

Running multiple Grafana instances

If you run multiple instances of Grafana, add a version number to each data source in the configuration and increase it when you update the configuration. Grafana updates only data sources with the same or lower version number than specified in the config. This prevents old configurations from overwriting newer ones if you have different versions of the datasource.yaml file that don’t define version numbers, and then restart instances at the same time.

Example data source config file

This example provisions a Graphite data source:

# Configuration file version
apiVersion: 1

# List of data sources to delete from the database.
deleteDatasources:
  - name: Graphite
    orgId: 1

# List of data sources to insert/update depending on what's
# available in the database.
datasources:
  # <string, required> Sets the name you use to refer to
  # the data source in panels and queries.
  - name: Graphite
    # <string, required> Sets the data source type.
    type: graphite
    # <string, required> Sets the access mode, either
    # proxy or direct (Server or Browser in the UI).
    # Some data sources are incompatible with any setting
    # but proxy (Server).
    access: proxy
    # <int> Sets the organization id. Defaults to orgId 1.
    orgId: 1
    # <string> Sets a custom UID to reference this
    # data source in other parts of the configuration.
    # If not specified, Grafana generates one.
    uid: my_unique_uid
    # <string> Sets the data source's URL, including the
    # port.
    url: http://localhost:8080
    # <string> Sets the database user, if necessary.
    user:
    # <string> Sets the database name, if necessary.
    database:
    # <bool> Enables basic authorization.
    basicAuth:
    # <string> Sets the basic authorization username.
    basicAuthUser:
    # <bool> Enables credential headers.
    withCredentials:
    # <bool> Toggles whether the data source is pre-selected
    # for new panels. You can set only one default
    # data source per organization.
    isDefault:
    # <map> Fields to convert to JSON and store in jsonData.
    jsonData:
      # <string> Defines the Graphite service's version.
      graphiteVersion: '1.1'
      # <bool> Enables TLS authentication using a client
      # certificate configured in secureJsonData.
      tlsAuth: true
      # <bool> Enables TLS authentication using a CA
      # certificate.
      tlsAuthWithCACert: true
    # <map> Fields to encrypt before storing in jsonData.
    secureJsonData:
      # <string> Defines the CA cert, client cert, and
      # client key for encrypted authentication.
      tlsCACert: '...'
      tlsClientCert: '...'
      tlsClientKey: '...'
      # <string> Sets the database password, if necessary.
      password:
      # <string> Sets the basic authorization password.
      basicAuthPassword:
    # <int> Sets the version. Used to compare versions when
    # updating. Ignored when creating a new data source.
    version: 1
    # <bool> Allows users to edit data sources from the
    # Grafana UI.
    editable: false

For provisioning examples of specific data sources, refer to that data source’s documentation.

JSON Data

Since not all data sources have the same configuration settings, we include only the most common ones as fields. To provision the rest of a data source’s settings, include them as a JSON blob in the jsonData field.

Common settings in the built-in core data sources include:

Note
Data sources tagged with HTTP* communicate using the HTTP protocol, which includes all core data source plugins except MySQL, PostgreSQL, and MSSQL.

Name	Type	Data source	Description
tlsAuth	boolean	HTTP*, MySQL	Enable TLS authentication using client cert configured in secure json data
tlsAuthWithCACert	boolean	HTTP*, MySQL, PostgreSQL	Enable TLS authentication using CA cert
tlsSkipVerify	boolean	HTTP*, MySQL, PostgreSQL, MSSQL	Controls whether a client verifies the server’s certificate chain and host name.
serverName	string	HTTP*, MSSQL	Optional. Controls the server name used for certificate common name/subject alternative name verification. Defaults to using the data source URL.
timeout	string	HTTP*	Request timeout in seconds. Overrides dataproxy.timeout option
graphiteVersion	string	Graphite	Graphite version
timeInterval	string	Prometheus, Elasticsearch, InfluxDB, MySQL, PostgreSQL and MSSQL	Lowest interval/step value that should be used for this data source.
httpMode	string	Influxdb	HTTP Method. ‘GET’, ‘POST’, defaults to GET
maxSeries	number	Influxdb	Max number of series/tables that Grafana processes
httpMethod	string	Prometheus	HTTP Method. ‘GET’, ‘POST’, defaults to POST
customQueryParameters	string	Prometheus	Query parameters to add, as a URL-encoded string.
manageAlerts	boolean	Prometheus and Loki	Manage alerts via Alerting UI
alertmanagerUid	string	Prometheus and Loki	UID of Alert Manager that manages Alert for this data source.
timeField	string	Elasticsearch	Which field that should be used as timestamp
interval	string	Elasticsearch	Index date time format. nil(No Pattern), ‘Hourly’, ‘Daily’, ‘Weekly’, ‘Monthly’ or ‘Yearly’
logMessageField	string	Elasticsearch	Which field should be used as the log message
logLevelField	string	Elasticsearch	Which field should be used to indicate the priority of the log message
maxConcurrentShardRequests	number	Elasticsearch	Maximum number of concurrent shard requests that each sub-search request executes per node
sigV4Auth	boolean	Elasticsearch and Prometheus	Enable usage of SigV4
sigV4AuthType	string	Elasticsearch and Prometheus	SigV4 auth provider. default/credentials/keys
sigV4ExternalId	string	Elasticsearch and Prometheus	Optional SigV4 External ID
sigV4AssumeRoleArn	string	Elasticsearch and Prometheus	Optional SigV4 ARN role to assume
sigV4Region	string	Elasticsearch and Prometheus	SigV4 AWS region
sigV4Profile	string	Elasticsearch and Prometheus	Optional SigV4 credentials profile
authType	string	Cloudwatch	Auth provider. default/credentials/keys
externalId	string	Cloudwatch	Optional External ID
assumeRoleArn	string	Cloudwatch	Optional ARN role to assume
defaultRegion	string	Cloudwatch	Optional default AWS region
customMetricsNamespaces	string	Cloudwatch	Namespaces of Custom Metrics
profile	string	Cloudwatch	Optional credentials profile
tsdbVersion	string	OpenTSDB	Version
tsdbResolution	string	OpenTSDB	Resolution
sslmode	string	PostgreSQL	SSLmode. ‘disable’, ‘require’, ‘verify-ca’ or ‘verify-full’
tlsConfigurationMethod	string	PostgreSQL	SSL Certificate configuration, either by ‘file-path’ or ‘file-content’
sslRootCertFile	string	PostgreSQL, MSSQL	SSL server root certificate file, must be readable by the Grafana user
sslCertFile	string	PostgreSQL	SSL client certificate file, must be readable by the Grafana user
sslKeyFile	string	PostgreSQL	SSL client key file, must be readable by only the Grafana user
encrypt	string	MSSQL	Determines SSL encryption handling. Options include: `disable` - data sent between client and server is not encrypted; `false` - data sent between client and server is not encrypted beyond the login packet; `true` - data sent between client and server is encrypted. Default is `false`.
postgresVersion	number	PostgreSQL	Postgres version as a number (903/904/905/906/1000) meaning v9.3, v9.4, …, v10
timescaledb	boolean	PostgreSQL	Enable usage of TimescaleDB extension
maxOpenConns	number	MySQL, PostgreSQL and MSSQL	Maximum number of open connections to the database (Grafana v5.4+)
maxIdleConns	number	MySQL, PostgreSQL and MSSQL	Maximum number of connections in the idle connection pool (Grafana v5.4+)
connMaxLifetime	number	MySQL, PostgreSQL and MSSQL	Maximum amount of time in seconds a connection may be reused (Grafana v5.4+)
keepCookies	array	HTTP*	Cookies that needs to be passed along while communicating with data sources
prometheusVersion	string	Prometheus	The version of the Prometheus data source, such as `2.37.0`, `2.24.0`
prometheusType	string	Prometheus	Prometheus database type. Options are `Prometheus`, `Cortex`, `Mimir` or`Thanos`.
cacheLevel	string	Prometheus	Determines the duration of the browser cache. Valid values include: `Low`, `Medium`, `High`, and `None`. This field is configurable when you enable the `prometheusResourceBrowserCache` feature flag.
incrementalQuerying	string	Prometheus	Experimental: Turn on incremental querying to enhance dashboard reload performance with slow data sources
incrementalQueryOverlapWindow	string	Prometheus	Experimental: Configure incremental query overlap window. Requires a valid duration string, i.e. `180s` or `15m` Default value is `10m` (10 minutes).
disableRecordingRules	boolean	Prometheus	Experimental: Turn off Prometheus recording rules
implementation	string	AlertManager	The implementation of the AlertManager data source, such as `prometheus`, `cortex` or `mimir`
handleGrafanaManagedAlerts	boolean	AlertManager	When enabled, Grafana-managed alerts are sent to this Alertmanager

For examples of specific data sources’ JSON data, refer to that data source’s documentation.

Secure JSON Data

Secure JSON data is a map of settings that will be encrypted with secret key from the Grafana config. The purpose of this is only to hide content from the users of the application. This should be used for storing TLS Cert and password that Grafana will append to the request on the server side. All of these settings are optional.

Note
The HTTP* tag denotes data sources that communicate using the HTTP protocol, including all core data source plugins except MySQL, PostgreSQL, and MSSQL.

Name	Type	Data source	Description
tlsCACert	string	HTTP*, MySQL, PostgreSQL	CA cert for out going requests
tlsClientCert	string	HTTP*, MySQL, PostgreSQL	TLS Client cert for outgoing requests
tlsClientKey	string	HTTP*, MySQL, PostgreSQL	TLS Client key for outgoing requests
password	string	HTTP*, MySQL, PostgreSQL, MSSQL	password
basicAuthPassword	string	HTTP*	password for basic authentication
accessKey	string	Cloudwatch	Access key for connecting to Cloudwatch
secretKey	string	Cloudwatch	Secret key for connecting to Cloudwatch
sigV4AccessKey	string	Elasticsearch and Prometheus	SigV4 access key. Required when using keys auth provider
sigV4SecretKey	string	Elasticsearch and Prometheus	SigV4 secret key. Required when using keys auth provider

Custom HTTP headers for data sources

Data sources managed by Grafanas provisioning can be configured to add HTTP headers to all requests going to that data source. The header name is configured in the jsonData field and the header value should be configured in secureJsonData.

apiVersion: 1

datasources:
  - name: Graphite
    jsonData:
      httpHeaderName1: 'HeaderName'
      httpHeaderName2: 'Authorization'
    secureJsonData:
      httpHeaderValue1: 'HeaderValue'
      httpHeaderValue2: 'Bearer XXXXXXXXX'

Plugins

Note
Available in Grafana v7.1 and higher.

You can manage plugin applications in Grafana by adding one or more YAML config files in the provisioning/plugins directory. Each config file can contain a list of apps that will be updated during start up. Grafana updates each app to match the configuration file.

Note
This feature enables you to provision plugin configurations, not the plugins themselves. The plugins must already be installed on the Grafana instance.

Example plugin configuration file

apiVersion: 1

apps:
  # <string> the type of app, plugin identifier. Required
  - type: raintank-worldping-app
    # <int> Org ID. Default to 1, unless org_name is specified
    org_id: 1
    # <string> Org name. Overrides org_id unless org_id not specified
    org_name: Main Org.
    # <bool> disable the app. Default to false.
    disabled: false
    # <map> fields that will be converted to json and stored in jsonData. Custom per app.
    jsonData:
      # key/value pairs of string to object
      key: value
    # <map> fields that will be converted to json, encrypted and stored in secureJsonData. Custom per app.
    secureJsonData:
      # key/value pairs of string to string
      key: value

Dashboards

You can manage dashboards in Grafana by adding one or more YAML config files in the provisioning/dashboards directory. Each config file can contain a list of dashboards providers that load dashboards into Grafana from the local filesystem.

The dashboard provider config file looks somewhat like this:

apiVersion: 1

providers:
  # <string> an unique provider name. Required
  - name: 'a unique provider name'
    # <int> Org id. Default to 1
    orgId: 1
    # <string> name of the dashboard folder.
    folder: ''
    # <string> folder UID. will be automatically generated if not specified
    folderUid: ''
    # <string> provider type. Default to 'file'
    type: file
    # <bool> disable dashboard deletion
    disableDeletion: false
    # <int> how often Grafana will scan for changed dashboards
    updateIntervalSeconds: 10
    # <bool> allow updating provisioned dashboards from the UI
    allowUiUpdates: false
    options:
      # <string, required> path to dashboard files on disk. Required when using the 'file' type
      path: /var/lib/grafana/dashboards
      # <bool> use folder names from filesystem to create folders in Grafana
      foldersFromFilesStructure: true

When Grafana starts, it will update/insert all dashboards available in the configured path. Then later on poll that path every updateIntervalSeconds and look for updated json files and update/insert those into the database.

Note: Dashboards are provisioned to the root level if the folder option is missing or empty.

Making changes to a provisioned dashboard

It’s possible to make changes to a provisioned dashboard in the Grafana UI. However, it is not possible to automatically save the changes back to the provisioning source. If allowUiUpdates is set to true and you make changes to a provisioned dashboard, you can Save the dashboard then changes will be persisted to the Grafana database.

Note: If a provisioned dashboard is saved from the UI and then later updated from the source, the dashboard stored in the database will always be overwritten. The version property in the JSON file will not affect this, even if it is lower than the existing dashboard.

If a provisioned dashboard is saved from the UI and the source is removed, the dashboard stored in the database will be deleted unless the configuration option disableDeletion is set to true.

If allowUiUpdates is configured to false, you are not able to make changes to a provisioned dashboard. When you click Save, Grafana brings up a Cannot save provisioned dashboard dialog. The screenshot below illustrates this behavior.

Grafana offers options to export the JSON definition of a dashboard. Either Copy JSON to Clipboard or Save JSON to file can help you synchronize your dashboard changes back to the provisioning source.

Note: The JSON definition in the input field when using Copy JSON to Clipboard or Save JSON to file will have the id field automatically removed to aid the provisioning workflow.

Reusable Dashboard URLs

If the dashboard in the JSON file contains an UID, Grafana forces insert/update on that UID. This allows you to migrate dashboards between Grafana instances and provisioning Grafana from configuration without breaking the URLs given because the new dashboard URL uses the UID as identifier. When Grafana starts, it updates/inserts all dashboards available in the configured folders. If you modify the file, then the dashboard is also updated. By default, Grafana deletes dashboards in the database if the file is removed. You can disable this behavior using the disableDeletion setting.

Note
Provisioning allows you to overwrite existing dashboards which leads to problems if you reuse settings that are supposed to be unique. Be careful not to reuse the same title multiple times within a folder or uid within the same installation as this will cause weird behaviors.

Provision folders structure from filesystem to Grafana

If you already store your dashboards using folders in a git repo or on a filesystem, and also you want to have the same folder names in the Grafana menu, you can use foldersFromFilesStructure option.

For example, to replicate these dashboards structure from the filesystem to Grafana,

/etc/dashboards
├── /server
│   ├── /common_dashboard.json
│   └── /network_dashboard.json
└── /application
    ├── /requests_dashboard.json
    └── /resources_dashboard.json

you need to specify just this short provision configuration file.

apiVersion: 1

providers:
  - name: dashboards
    type: file
    updateIntervalSeconds: 30
    options:
      path: /etc/dashboards
      foldersFromFilesStructure: true

server and application will become new folders in Grafana menu.

Note
folder and folderUid options should be empty or missing to make foldersFromFilesStructure work.

Note
To provision dashboards to the root level, store them in the root of your path.

Note
This feature doesn’t currently allow you to create nested folder structures, that is, where you have folders within folders.

Alerting

For information on provisioning Grafana Alerting, refer to Provision Grafana Alerting resources.

Supported Settings

The following sections detail the supported settings and secure settings for each alert notification type. Secure settings are stored encrypted in the database and you add them to secure_settings in the YAML file instead of settings.

Note
Secure settings is supported since Grafana v7.2.

Alert notification `pushover`

Name	Secure setting
apiToken	yes
userKey	yes
device
priority
okPriority
retry
expire
sound
okSound

Alert notification `discord`

Name	Secure setting
url	yes
avatar_url
content
use_discord_username

Alert notification `slack`

Name	Secure setting
url	yes
recipient
username
icon_emoji
icon_url
uploadImage
mentionUsers
mentionGroups
mentionChannel
token	yes

Alert notification `victorops`

Name
url
autoResolve

Alert notification `kafka`

Name
kafkaRestProxy
kafkaTopic

Alert notification `LINE`

Name	Secure setting
token	yes

Alert notification `pagerduty`

Name	Secure setting
integrationKey	yes
autoResolve

Alert notification `sensu`

Name	Secure setting
url
source
handler
username
password	yes

Alert notification `sensugo`

Name	Secure setting
url
apikey	yes
entity
check
handler
namespace

Alert notification `prometheus-alertmanager`

Name	Secure setting
url
basicAuthUser
basicAuthPassword	yes

Alert notification `teams`

Name
url

Alert notification `dingding`

Name
url

Alert notification `email`

Name
singleEmail
addresses

Alert notification `hipchat`

Name
url
apikey
roomid

Alert notification `opsgenie`

Name	Secure setting
apiKey	yes
apiUrl
autoClose
overridePriority
sendTagsAs

Alert notification `telegram`

Name	Secure setting
bottoken	yes
chatid
uploadImage

Alert notification `threema`

Name	Secure setting
gateway_id
recipient_id
api_secret	yes

Alert notification `webhook`

Name	Secure setting
url
httpMethod
username
password	yes

Alert notification `googlechat`

Name
url

Alert notification `Cisco Webex Teams`

Name	Secure setting
message
room_id
api_url
bot_token	yes

Grafana Enterprise

Grafana Enterprise supports:

API keys

Mon, 16 Mar 2026 19:38:33 +0000

API keys

Note
Deprecated: Service accounts have replaced API keys as the primary way to authenticate applications that interact with Grafana.

An API key is a randomly generated string that external systems use to interact with Grafana HTTP APIs.

When you create an API key, you specify a Role that determines the permissions associated with the API key. Role permissions control that actions the API key can perform on Grafana resources.

Note
If you use Grafana v9.1 or newer, use service accounts instead of API keys. For more information, refer to Grafana service accounts.

Create an API key

Create an API key when you want to manage your computed workload with a user.

This topic shows you how to create an API key using the Grafana UI. You can also create an API key using the Grafana HTTP API. For more information about creating API keys via the API, refer to Create API key via API.

Before you begin

To follow these instructions, you need at least one of the following:

Administrator permissions
Editor permissions
Service account writer
To ensure you have permission to create and edit API keys, follow the instructions in Roles and permissions.

Steps

To create an API key, complete the following steps:

Sign in to Grafana.
Click Administration in the left-side menu, Users and access, and select API Keys.
Click Add API key.
Enter a unique name for the key.
In the Role field, select one of the following access levels you want to assign to the key.
- Admin: Enables a user to use APIs at the broadest, most powerful administrative level.
- Editor or Viewer to limit the key’s users to those levels of power.
In the Time to live field, specify how long you want the key to be valid.
- The maximum length of time is 30 days (one month). You enter a number and a letter. Valid letters include s for seconds,m for minutes, h for hours, d for days, w for weeks, and M for month. For example, 12h is 12 hours and 1M is 1 month (30 days).
- If you are unsure about how long an API key should be valid, we recommend that you choose a short duration, such as a few hours. This approach limits the risk of having API keys that are valid for a long time.
Click Add.

Migrate API keys to Grafana service accounts

As an alternative to using API keys for authentication, you can use a service account-based authentication system. When compared to API keys, service accounts have limited scopes that provide more security than using API keys.

For more information about the benefits of service accounts, refer to Grafana service account benefits.

The service account endpoints generate a machine user for authentication instead of using API keys. When you migrate an API key to a service account, a service account will be created with a service account token.

Note
If you’re currently using API keys for authentication, we strongly recommend to use Grafana Service Accounts instead. Rest assured, when migrating to Service Accounts, your existing API keys will continue working as before. To find the migrated API keys, navigate to the Service Accounts section and select the Service Account Tokens tab. For more information, please refer to the Grafana service account tokens details.

Ways of migrating API keys to service accounts

If you are currently using API keys in your environment, you need to reconfigure your setup to use service accounts.

Depending on your current setup, you may need to use one or all of the following methods to migrate your environment to service accounts:

The Grafana user interface: Use this method if you have been using the UI to manage your API keys and want to switch to using service accounts.
The Grafana API: Use this method if you have been using API calls to manage your API keys and want to switch to using service accounts programmatically.
Terraform: If you have a Terraform configuration that sets up API keys, you need to reconfigure your Terraform to use service accounts instead.

By following these steps, you can successfully migrate your integration from API keys to service accounts and continue using Grafana seamlessly.

Migrate API keys to Grafana service accounts using the Grafana user interface

This section shows you how to migrate API keys to Grafana service accounts using the Grafana user interface. You can choose to migrate a single API key or all API keys. When you migrate all API keys, you can no longer create API keys and must use service accounts instead.

Before you begin

To follow these instructions, you need at least one of the following:

Administrator permissions
Editor permissions
Service account writer

For more information about permissions, refer to Roles and permissions.

Steps

To migrate all API keys to service accounts, complete the following steps:

Sign in to Grafana, point to Administration, Users and access, and click API Keys.
In the top of the page, find the section which says Switch from API keys to service accounts
Click Migrate to service accounts now.
A confirmation window will appear, asking to confirm the migration. Click Yes, migrate now if you are willing to continue.
Once migration is successful, you can choose to forever hide the API keys page. Click Hide API keys page forever if you want to do that.

To migrate a single API key to a service account, complete the following steps:

Sign in to Grafana.
Click Administration in the left-side menu, Users and access, and select API Keys.
Find the API Key you want to migrate.
Click Migrate to service account.

Migrate API keys to Grafana service accounts for API calls

This section shows you how to migrate API keys to Grafana service accounts for Grafana API workflows. For references see: Grafana Service Accounts for the Grafana API.

Before you begin

To follow these instructions, you need one of the following:

Administrator permissions
Editor permissions
Service account writer

Steps

Complete the following steps to migrate from API keys to service accounts for API:

Call the POST /api/serviceaccounts endpoint and the POST /api/serviceaccounts/<id>/tokens.

This action generates a service account token.
Store the ID and secret that the system returns to you.
Pass the token in the Authorization header, prefixed with Bearer.

This action authenticates API requests.
SATs used for authentication
Remove code that handles the old /api/auth/keys endpoint.
Track the API keys in use and migrate them to SATs.

Example

Your current setup

curl -X POST -H "Content-Type: application/json" -d '{"name": "my-api-key", "role": "Viewer"}' http://admin:admin@localhost:3000/api/auth/keys

# response from the api
{"id":2,"name":"my-api-key","key":"eyJrIjoiTFRSN1RBOVc3SGhjblc0bWZodXZ3MnNDcU92Um5VZUIiLKJuIjoibXktYXBpLWtleSIsImlkIjoxfQ=="}%

New setup

# create a service account
curl -X POST -H "Content-Type: application/json" -d '{"name": "my-service-account", "role": "Viewer"}' http://admin:admin@localhost:3000/api/serviceaccounts

# response with the created service account id,name, login
{"id":1,"name":"my-service-account","login":"sa-my-service-account","orgId":1,"isDisabled":false,"role":"Viewer","tokens":0,"avatarUrl":""}%

# create the service account token with the service account id 1 - /serviceaccounts/{id} returned from the previous step
curl -X POST -H "Content-Type: application/json" -d '{"name": "my-service-account-token"}' http://admin:admin@localhost:3000/api/serviceaccounts/1/tokens

# response with the created SAT id,name and key.
{"id":2,"name":"my-service-account-token","key":"glsa_9244xlVFZK0j8Lh4fU8Cz6Z5tO664zIi_7a762939"}%

# now you can authenticate the same way as you did with the API key
curl --request GET --url http://localhost:3000/api/folders --header 'Authorization: Bearer glsa_9244xlVFZK0j8Lh4fU8Cz6Z5tO664zIi_7a762939'

# response
[{"id":1,"uid":"a5261a84-eebc-4733-83a9-61f4713561d1","title":"gdev dashboards"}]%

Migrate API keys to Grafana service accounts in Terraform

Note
The terraform resource api_key is removed from the Grafana Terraform Provider in v3.0.0. Before you migrate and remove the use of the resource, you should pin your terraform version to a version less-than or equal-to v2.19.0. For more information, refer to the Grafana Terraform Provider release notes.

To pin the Grafana Terraform Provider to v2.19.0:

terraform {
  required_providers {
    grafana = {
      source  = "grafana/grafana"
      version = "2.19.0"
    }
  }
}

This section shows you how to migrate your Terraform configuration for API keys to Grafana service accounts. For resources, see Grafana Service Accounts in Terraform.

For migration your cloud stack api keys, use the grafana_cloud_stack_service_account and gafana_cloud_stack_service_account_token resources see Grafana Cloud Stack Service Accounts in Terraform.

Steps

Complete the following steps to migrate from API keys to service accounts using Terraform:

Generate grafana_service_account and grafana_service_account_token resources.
Specify the desired scopes and expiration date when creating the service account.
Use the token returned from grafana_service_account_token to authenticate the API requests.
Remove the terraform configuration for creating your grafana_api_key resources.

Example: your current Terraform configuration

terraform {
  required_providers {
    grafana = {
      source  = "grafana/grafana"
    }
  }
}

# configure the provider with basic auth
provider "grafana" {
  url  = "http://localhost:3000"
  auth = "admin:admin"
}

resource "grafana_api_key" "foo" {
  name = "key_foo"
  role = "Viewer"
}

resource "grafana_api_key" "bar" {
  name            = "key_bar"
  role            = "Admin"
  seconds_to_live = 30
}

Your new Terraform configuration

Note: you can create multiple tokens using one service account.

terraform {
  required_providers {
    grafana = {
      source  = "grafana/grafana"
    }
  }
}

# configure the provider with basic auth
provider "grafana" {
  url  = "http://localhost:3000"
  auth = "admin:admin"
}

# Creating a service account in Grafana instance to be used as auth and attach tokens
# notice we can attach multiple tokens to one service account
resource "grafana_service_account" "sa-admin" {
  name             = "sa-admin"
  role             = "Admin"
}

# Creating a service account token in Grafana instance to be used for creating resources in Grafana instance
resource "grafana_service_account_token" "sat-bar" {
  name           = "sat-bar"
  service_account_id = grafana_service_account.sa-admin.id
}

# Creating a service account token in Grafana instance to be used for creating resources in Grafana instance
resource "grafana_service_account_token" "sat-foo" {
  name           = "sat-foo"
  service_account_id = grafana_service_account.sa-admin.id
  seconds_to_live    = 30
}

Migrate Cloud Stack API keys to Grafana cloud stack service accounts in Terraform

This section shows you how to migrate your Terraform configuration for Grafana cloud stack API keys to Grafana cloud stack service accounts. For migration your cloud stack api keys, use the grafana_cloud_stack_service_account and gafana_cloud_stack_service_account_token resources see Grafana Cloud Stack Service Accounts in Terraform.

Note
This is only relevant for Grafana Cloud Stack API keys grafana_cloud_stack_api_key. Grafana Cloud API keys resource grafana_cloud_api_key are not deprecated and should be used for authentication for managing your Grafana cloud.

Steps

Complete the following steps to migrate from cloud stack API keys to cloud stack service accounts using Terraform:

Generate grafana_cloud_stack_service_account and grafana_cloud_stack_service_account_token resources.
Specify the desired scopes and expiration date when creating the service account.
Use the token returned from grafana_cloud_stack_service_account_token to authenticate the API requests.
Remove the Terraform configuration for creating your grafana_cloud_stack_api_key resources.

Example: Your current Terraform configuration

terraform {
  required_providers {
    grafana = {
      source = "grafana/grafana"
    }
  }
}

# Declaring the first provider to be only used for creating the cloud-stack
provider "grafana" {
  alias = "cloud"

  cloud_api_key = "<API-Key>"
}

resource "grafana_cloud_stack" "my_stack" {
  provider = grafana.cloud

  name        = "my_stack"
  slug        = "my_stack"
  region_slug = "eu" # Example “us”,”eu” etc
}

# Creating a Grafana API key to be used as auth
resource "grafana_cloud_stack_api_key" "management" {
  provider = grafana.cloud

  stack_slug = grafana_cloud_stack.my_stack.slug
  name       = "management-key"
  role       = "Admin"
}

Your new Terraform configuration

terraform {
  required_providers {
    grafana = {
      source = "grafana/grafana"
    }
  }
}

# Declaring the first provider to be only used for creating the cloud-stack
provider "grafana" {
  alias = "cloud"

  cloud_api_key = "<API-Key>"
}

resource "grafana_cloud_stack" "my_stack" {
  provider = grafana.cloud

  name        = "my_stack"
  slug        = "my_stack"
  region_slug = "eu" # Example “us”,”eu” etc
}

# Creating a grafana cloud stack service account
resource "grafana_cloud_stack_service_account" "mystack_cloud-stack_service_account" {
  provider   = grafana.cloud
  stack_slug = grafana_cloud_stack.my_stack.slug

  name = "mystack-cloud-stack-sa"
  role = "Admin"
}

# Creating a grafana cloud stack service account token
resource "grafana_cloud_stack_service_account_token" "mystack_cloud-stack_service-account_token" {
  provider   = grafana.cloud
  stack_slug = grafana_cloud_stack.my_stack.slug

  name               = "mystack-cloud-stack-sa-token"
  service_account_id = grafana_cloud_stack_service_account.mystack_cloud-stack_service_account.id
}

Service accounts

Mon, 16 Mar 2026 19:38:33 +0000

Service accounts

You can use a service account to run automated workloads in Grafana, such as dashboard provisioning, configuration, or report generation. Create service accounts and tokens to authenticate applications, such as Terraform, with the Grafana API.

Note
Service accounts replace API keys as the primary way to authenticate applications that interact with Grafana.

A common use case for creating a service account is to perform operations on automated or triggered tasks. You can use service accounts to:

Schedule reports for specific dashboards to be delivered on a daily/weekly/monthly basis
Define alerts in your system to be used in Grafana
Set up an external SAML authentication provider
Interact with Grafana without signing in as a user

In Grafana Enterprise, you can also use service accounts in combination with role-based access control to grant very specific permissions to applications that interact with Grafana.

Note
Service accounts can only act in the organization they are created for. If you have the same task that is needed for multiple organizations, we recommend creating service accounts in each organization.

Video shows service accounts in Grafana v9.1. Refer to Create a service account in Grafana for current instructions.

Service account tokens

A service account token is a generated random string that acts as an alternative to a password when authenticating with Grafana’s HTTP API.

When you create a service account, you can associate one or more access tokens with it. You can use service access tokens the same way as API Keys, for example to access Grafana HTTP API programmatically.

You can create multiple tokens for the same service account. You might want to do this if:

multiple applications use the same permissions, but you would like to audit or manage their actions separately.
you need to rotate or replace a compromised token.

Service account access tokens inherit permissions from the service account.

Service account benefits

The added benefits of service accounts to API keys include:

Service accounts resemble Grafana users and can be enabled/disabled, granted specific permissions, and remain active until they are deleted or disabled. API keys are only valid until their expiry date.
Service accounts can be associated with multiple tokens.
Unlike API keys, service account tokens are not associated with a specific user, which means that applications can be authenticated even if a Grafana user is deleted.
You can grant granular permissions to service accounts by leveraging role-based access control. For more information about permissions, refer to About users and permissions.

Create a service account in Grafana

A service account can be used to run automated workloads in Grafana, like dashboard provisioning, configuration, or report generation. For more information about how you can use service accounts, refer to About service accounts.

For more information about creating service accounts via the API, refer to Create a service account in the HTTP API.

Note that the user who created a service account will also be able to read, update and delete the service account that they created, as well as permissions associated with that service account.

Before you begin

Ensure you have permission to create and edit service accounts. By default, the organization administrator role is required to create and edit service accounts. For more information about user permissions, refer to About users and permissions.

To create a service account

Sign in to Grafana and click Administration in the left-side menu.
Click Users and access.
Click Service accounts.
Click Add service account.
Enter a Display name.
The display name must be unique as it determines the ID associated with the service account.
- We recommend that you use a consistent naming convention when you name service accounts. A consistent naming convention can help you scale and maintain service accounts in the future.
- You can change the display name at any time.
Click Create.

Add a token to a service account in Grafana

A service account token is a generated random string that acts as an alternative to a password when authenticating with Grafana’s HTTP API. For more information about service accounts, refer to About service accounts in Grafana.

You can create a service account token using the Grafana UI or via the API. For more information about creating a service account token via the API, refer to Create service account tokens using the HTTP API.

Before you begin

Ensure you have permission to create and edit service accounts. By default, the organization administrator role is required to create and edit service accounts. For more information about user permissions, refer to About users and permissions.

Service account token expiration dates

By default, service account tokens don’t have an expiration date, meaning they won’t expire at all. However, if token_expiration_day_limit is set to a value greater than 0, Grafana restricts the lifetime limit of new tokens to the configured value in days.

To add a token to a service account

Sign in to Grafana and click Administration in the left-side menu.
Click Users and access.
Click Service accounts.
Click the service account to which you want to add a token.
Click Add service account token.
Enter a name for the token.
(recommended) Select Set expiration date and enter an expiry date for the token.
- The expiry date specifies how long you want the key to be valid.
- If you are unsure of an expiration date, we recommend that you set the token to expire after a short time, such as a few hours or less. This limits the risk associated with a token that is valid for a long time.
Click Generate token.

Assign roles to a service account in Grafana

You can assign roles to a Grafana service account to control access for the associated service account tokens. You can assign roles to a service account using the Grafana UI or via the API. For more information about assigning a role to a service account via the API, refer to Update service account using the HTTP API.

In Grafana Enterprise, you can also assign RBAC roles to grant very specific permissions to applications that interact with Grafana.

Note
Since Grafana 10.2.0, the No Basic Role is available for organization users or service accounts. This role has no permissions. Permissions can be granted with RBAC.

Before you begin

Ensure you have permission to update service accounts roles. By default, the organization administrator role is required to update service accounts permissions. For more information about user permissions, refer to About users and permissions.

To assign a role to a service account

Sign in to Grafana and click Administration in the left-side menu.
Click Users and access.
Click Service accounts.
Click the service account to which you want to assign a role. As an alternative, find the service account in the list view.
Assign a role using the role picker to update.

Manage users and teams permissions for a service account in Grafana

To control what and who can do with the service account you can assign permissions directly to users and teams. You can assign permissions using the Grafana UI.

Before you begin

Ensure you have permission to update user and team permissions of a service accounts. By default, the organization administrator role is required to update user and teams permissions for a service account. For more information about user permissions, refer to About users and permissions.
Ensure you have permission to read teams.

User and team permissions for a service account

You can assign on of the following permissions to a specific user or a team:

Edit: A user or a team with this permission can view, edit, enable and disable a service account, and add or delete service account tokens.
Admin: User or a team with this permission will be able to everything from Edit permission, as well as manage user and team permissions for a service account.

To update team permissions for a service account

Sign in to Grafana and click Administration in the left-side menu.
Click Users and access.
Click Service accounts.
Click the service account for which you want to update team permissions a role.
In the Permissions section at the bottom, click Add permission.
Choose Team in the dropdown and select your desired team.
Choose View, Edit or Admin role in the dropdown and click Save.

To update user permissions for a service account

Sign in to Grafana and click Administration in the left-side menu.
Click Users and access.
Click Service accounts.
Click the service account for which you want to update team permissions a role.
In the Permissions section at the bottom, click Add permission.
Choose User in the dropdown and select your desired user.
Choose View, Edit or Admin role in the dropdown and click Save.

Debug the permissions of a service account token

This section explains how to learn which RBAC permissions are attached to a service account token. This can help you diagnose permissions-related issues with token authorization.

Before you begin

These endpoints provide details on a service account’s token. If you haven’t added a token to a service account, do so before proceeding. For details, refer to Add a token to a service account.

List a service account token’s permissions

To list your token’s permissions, use the /api/access-control/user/permissions endpoint.

Example

Note
The following command output is shortened to show only the relevant content. Authorize your request with the token whose permissions you want to check.

curl -H "Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7FDsNSLAa_54e2f8be" -X GET '<grafana_url>/api/access-control/user/permissions' | jq

The output lists the token’s permissions:

{
  "dashboards:read": ["dashboards:uid:70KrY6IVz"],
  "dashboards:write": ["dashboards:uid:70KrY6IVz"],
  "datasources.id:read": ["datasources:*"],
  "datasources:read": ["datasources:*"],
  "datasources:explore": [""],
  "datasources:query": ["datasources:uid:grafana"],
  "datasources:read": ["datasources:uid:grafana"],
  "orgs:read": [""]
}

Check which dashboards a token is allowed to see

To list which dashboards a token can view, you can filter the /api/access-control/user/permissions endpoint’s response for the dashboards:read permission key.

Example

curl -H "Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7FDsNSLAa_54e2f8be" -X GET '<grafana_url>/api/access-control/user/permissions' | jq '."dashboards:read"'

The output lists the dashboards a token can view and the folders a token can view dashboards from, by their unique identifiers (uid):

[
  "dashboards:uid:70KrY6IVz",
  "dashboards:uid:d61be733D",
  "folders:uid:dBS87Axw2",
],

Correlations

Mon, 16 Mar 2026 19:38:33 +0000

Correlations

You can create interactive links for Explore visualizations to run queries related to presented data by setting up Correlations.

A correlation defines how data in one data source is used to query data in another data source. Some examples:

an application name returned in a logs data source can be used to query metrics related to that application in a metrics data source, or
a user name returned by an SQL data source can be used to query logs related to that particular user in a logs data source

Explore takes user-defined correlations to display links inside the visualizations. You can click on a link to run the related query and see results in Explore Split View.

Explore visualizations that currently support showing links based on correlations:

You can configure correlations using provisioning, the Administration > Plugins and data > Correlations page in Grafana or directly in Explore.

Example of how links work in Explore once set up

Feature toggles

Mon, 16 Mar 2026 19:38:33 +0000

Feature toggles

Grafana incorporates feature toggles which let you introduce new functionality safeguarded by control flags. This allows Grafana administrators the flexibility to determine the appropriate timing for enabling or disabling specific features. For detailed information about particular features and how they operate, refer to Configure Feature Toggles.

Manage feature toggles

In the Administration page, the Feature Management section enables authorized users to view and edit the various features that are active in their Grafana environment. Authorized users include administrators, and users with the fixed roles featuremgmt.read and featuremgmt.write.

There are different options for visibility and customization depending on the development stage of the feature.

Stage	Visibility	Editable
Experimental	Hidden	No
Private preview	Hidden	No
Public preview	Visible*	No
General availability	Visible*	Yes*
Deprecated	Visible*	Yes*

Note
Options marked with an asterisk (*) are defaults for the corresponding feature stage. Each feature toggle owner can override its default behavior.

Edit feature toggles

You can only edit feature toggles if Grafana is configured with the proper feature management settings. For more information, refer to Configure feature management.

Altering the state of a toggle may require restarting your Grafana instance, which can take a few minutes.

To edit a feature toggle, follow these steps:

Sign in to Grafana as a server administrator or authorized user.
In the primary menu, go to Administration > General > Feature toggles.
Navigate to the list of feature toggles and select your feature state overrides.
Click Save changes and wait for your Grafana instance to restart with the updated feature toggles.

Note
Editing feature toggles with the feature toggle management page is available now in all tiers of Grafana Cloud.

Administration on Grafana Labs

Back up Grafana

Back up Grafana

Back up the Grafana configuration file

Back up plugin data

Back up the Grafana database

SQLite

MySQL

Postgres

Data source management

Data source management

Data source permissions

Assign data source permissions to users, service accounts, teams, or roles

Edit data source permissions for users, service accounts, teams, or roles

Remove data source permissions for users, service accounts, teams, or roles

Query and resource caching

Caching benefits

Data sources that work with query caching

Enable and configure query caching

Disable query caching

Clear cache

Sending a request without cache

Grafana Teams

Grafana Teams

Teams concepts

Manage organizations

Manage organizations

About organizations

View a list of organizations

Before you begin

Create an organization

Before you begin

Delete an organization

Before you begin

Edit an organization

Before you begin

User management

User management

Recorded queries

Recorded queries

How recorded queries work

Using a recorded query

Create a recorded query

Add a recorded query

Manage recorded queries

Remote write target

Roles and permissions

Roles and permissions

Grafana server administrators

Organization users and permissions

Organization roles

Dashboard permissions

Editors with administrator permissions

Viewers with dashboard preview and Explore permissions

Teams and permissions

Grafana Enterprise user permissions features

Data source permissions

Role-based access control

Learn more

View server statistics and license

View server statistics and license

View Grafana server settings

View server settings

Available settings

View Grafana server stats

View server stats

Available stats

Counting users

Grafana Enterprise license

Grafana Enterprise license

Activate an Enterprise license

Step 1. Download your license file

Step 2. Add your license to a Grafana instance

Upload the license file via the Grafana server administrator page

Put the license.jwt file into the data directory of Grafana

Set the content of the license file as a configuration option

Step 3. Ensure that the license file’s root URL matches the root_url configuration option

Step 4. Restart Grafana

License expiration

Update your license

Put the `license.jwt` file into the data directory of Grafana