Grafana update: Service account tokens are replacing API keys

TL;DR

• All existing API keys will continue working seamlessly.
• Grafana Terraform provider api_key resource has been removed in v3.
• Scripts or provisioning tools such as Terraform that provision API keys in Grafana will need to migrate their automation to use service account tokens.

Enhancing security and providing flexible access control has always been part of our core mission at Grafana. In line with those efforts, we made service accounts generally available in Grafana 9.1.

Service accounts are essentially machines simulating Grafana users, and they are used to run automated workloads — for example, counting the number of data sources in Grafana every day or provisioning alerts using Terraform. These are tasks running in scripts or services outside of Grafana that require interacting with Grafana’s APIs.

The roll out of service accounts to authenticate applications prompted us to reevaluate the use of API keys, which have long been a primary authentication method for Grafana APIs. 

In assessing machine-to-machine interactions across Grafana overall, we found that supporting both API keys and service accounts increases security surface area and introduces additional operational costs. 

As a result, we are deprecating API keys in an effort to focus our efforts on supporting service accounts in Grafana. 

Moving forward, machine-to-machine authentication will be conducted through service account tokens (SATs), which offer enhanced security and provide more granular control over authentication and data access compared to traditional API keys.

How to migrate from API keys to service accounts

We have worked to ensure that the transition from API keys to service accounts will be as smooth as possible for developers. 

There are two different use cases to consider:

1. All existing API keys will continue working seamlessly and we will migrate them to SATs in January 2025; no action is required for API consumers authenticating with API keys. 
2. Scripts or tools such as Terraform that provision API keys in Grafana will need to migrate their automation to use service account tokens.

There is a detailed migration path from API keys to SATs starting with Grafana 9.1, and we encourage developers to complete this transition by Dec. 31, 2024, to avoid interruptions in their workflows.

Below is a detailed timeline for the deprecation of API keys in Grafana: 

• By Aug. 31, 2024: Creation of new API keys will no longer be possible.
• By Nov. 30, 2024: Developers relying on provisioned API keys via automation should migrate to SATs using the guidelines provided as of Grafana 9.1.
• By Jan. 31, 2025: We will migrate any remaining API keys to SATs automatically and remove the API key endpoints. Any automation relying on API key provisioning will stop working.

The Terraform resource api_key has been removed in v3.0.0 of the Grafana Terraform provider. During your migration path, if you need more time, we suggest that you pin your Terraform version to <v2.19.0.

Below are migration guidelines for the Grafana Terraform resource:

• By version 3.0: We will have removed the api_key resource from Grafana Terraform provider.
• Pinning to version 2.19: This follows the detailed timeline for the deprecation of the API keys in Grafana outlined above.

Learn more about service accounts in Grafana

Service accounts and SATs enhance security and make access control more flexible within Grafana. That’s because service accounts — unlike API keys — support granular, role-based access controls. To learn more and find out how to set up a service account, check out our service accounts documentation.  

With Grafana 11, the latest major release of our open source visualization tool that we unveiled at GrafanaCON 2024, we also rolled out new ways to securely scale Grafana within your organization. For a full demo on all the latest features, check out the “Grafana 11 deep dive” GrafanaCON session, which is available on demand today.   

Grafana Cloud is the easiest way to get started with metrics, logs, traces, dashboards, and more. We have a generous forever-free tier and plans for every use case. Sign up for free now!