Grafana Cloud Access Policies

Grafana Cloud Access Policies implement an authorization process for actions requested on Grafana Mimir (metrics), Grafana Loki (logs), Grafana Tempo (traces), and Grafana Cloud Alerts services, as well as for some Grafana Cloud API endpoints. This page describes cloud access policies concepts. To create an access policy and associated token, follow the instructions to authorize your service.

Caution
Grafana Cloud Access Policies have replaced Grafana Cloud API keys. Use access policies and tokens instead of Cloud API keys.

Access policies contain tokens, which grant other applications access to take certain actions on your Grafana Cloud hosted services. You can create one or more tokens for each access policy and use those tokens when configuring the Grafana Agent, setting up a Grafana data source, provisioning alerts, or otherwise interacting with Grafana Cloud’s APIs.

An individual access policy is composed of one or more scopes and a realm.

The scope is a specific action on a specific service. For example, the metrics:read scope defines an action that reads data from the Mimir service. The logs:write scope defines an action that creates data in the Loki service.

The realm identifies whether the scope will be applied during authorization to an org (organization) or to a stack (a set of services).

A decision to authorize an API request is made by comparing the request’s token with the associated Grafana Cloud access policy. If the API request performs an action that is allowed by an access policy (identified by the token), the API request is authorized.

In addition to scopes and realms, access policies also support IP range based access controls. For more information, refer to IP range based access control.

Grafana Cloud migration from API keys to access policies

A legacy Grafana Cloud API key with the proper role allows programmatic interaction with the Grafana Cloud API and hosted services. Each API key is linked to an organization and provides Admin, Editor, and Viewer roles. These roles apply at the organization level which includes all stacks and data within an organization. These API keys lack fine-grained access control: access is controlled only by a few roles.

To address this issue, Grafana Cloud Access Policies provide granular access control over Grafana Cloud by adding the ability to limit access to a single stack, select fine-grained scopes, define label filters, and set token expirations. One or more tokens are created for an access policy, and these tokens are only capable of what is defined within their access policy.

Capability	Legacy Grafana Cloud API keys	New Grafana Cloud Access Policies
Control based at which level	Organization level	Organization or stack level
Permissions	Viewer, Editor, Admin roles	Limited granular scopes
Token expiration	Not available	Available
Label-based access control	Not available	Available, with read scopes for metrics and logs
IP range based access control	Not available	Available

Use with the API, Grafana Stacks, and Cloud Portal

You can use access policies via the API, the Grafana Administration settings, and the Cloud Portal. The Grafana Cloud Access Policies API adds two new API endpoints points for access policies (/v1/accesspolicies) and tokens (/v1/tokens). These endpoints are described in the Grafana Cloud API documentation.

Access policy interface	Access policies for stacks	Access policies for an organization	Requires Cloud Portal Admin role	Requires Grafana Admin role
Cloud API	Yes	Yes	Yes	No
In a Grafana Stack	Single stack where created	No	No	Yes
Cloud Portal	Yes	Yes	Yes	No

The Access Policies page in the Cloud Portal lets you manage access policies and tokens across an organization and all of its stacks.

The Cloud access policies in the Grafana Administration settings allow access policies and tokens to be managed for a specific stack.

Access policies

Each access policy has one or more tokens, a realm, one or more scopes, and optional label filters. The table above summarizes access policies for stacks and organizations.

Each access policy has a unique name within an organization. Access policies are only used within one Grafana Cloud organization and do not span multiple organizations.

For more information about stacks and organizations, refer to the Grafana Cloud Stack section of Use the Cloud Portal to manage your Grafana Cloud account.

Realms

A realm has a type, such as organization or stack, an identifier, and a list of label policies. A realm must be specified when using the API or the Access Policies page in the Cloud Portal, but the realm is automatically set when managing access policies in the Grafana Administration settings.

You can specify an organization or stack ID. The org realm type can be used for applying access policies to any stack within an organization. If you specify a stack realm type, then the tokens under that particular policy can be used only for that stack.

Tokens

A token belongs to an access policy and is used programmatically to identify the entity that requests actions on resources. Authorization is based on rules defined by an access policy and the token presented with a request. An access policy can have one or more tokens.

Tokens are created in the same places as access policies. You can use the Cloud Access Policy API, the Access Policies page in the Cloud Portal, or the Cloud access policies page in the Grafana Administration settings. Any tokens defined in the Grafana Administration settings are limited to that Grafana’s stack.

Scopes

A scope defines which permissions a token has. For example, metrics:read, metrics:write, etc. Scopes let you specify which actions can be performed with resources such as metrics, logs, traces, alerts, rules, and access policies. Additional scopes are available within the Cloud Portal UI.

Service	Requested action	Permissions	Scope identifier
metrics	Publish or query metrics.	read, write	`metrics:read`, `metrics:write`
logs	Publish or query logs.	read, write	`logs:read`, `logs:write`
traces	Publish or query traces.	read, write	`traces:read`, `traces:write`
alerts	View or create alerts in alert manager or configure an instance of alert manager.	read, write	`alerts:read`, `alerts:write`
rules	View or create Prometheus alerting and recording rules	read, write	`rules:read`, `rules:write`
accesspolicies	View or create access policies and tokens	read, write, delete	`accesspolicies:read`, `accesspolicies: write`, `accesspolicies: delete`

The scopes you select limit the Grafana Cloud services you can query and the actions you can perform using the given access policy. Let’s say that you want to read metrics, traces, and logs and not write them. In this case, the access policy includes the metrics:read, logs:read, and traces:read scopes.

In the Grafana Administration settings, the same set of scopes, metrics:read, logs:read, and traces:read, are selected using checkboxes.

The available scopes in Cloud access policies within a stack.

The Access Policies page in the Cloud Portal also has these scopes. You can specify a different realm using the Access policies page in the Cloud Portal.

LabelPolicy or Label selectors

A LabelPolicy is a set of Prometheus label selectors used to limit metrics and logs data to specific label criteria. For example, adding a label policy of {env="dev"} returns matches from the dev environment. If you create an access policy with that label selector, then entities with a token for that access policy will only be able to query for metrics or logs that include the { env="dev" } label.

LabelPolicies are only available for reading logs and metrics.

In the Cloud Access Policies Plugin, LabelPolicies are referred to as Label selectors.

Refer to Using label-based access control with access policies for additional information.

IP range based access control

You can use IP range based access control with access policies to limit access to your Grafana Cloud services based on IP subnets. When configured, all tokens created under the access policy will obey the settings. Connections initiated from IP addresses outside of the specified ranges will be denied.

Refer to Using IP range based access control with access policies for additional information.