This is documentation for the next version of Grafana documentation. For the latest stable release, go to the latest version.
Roles and permissions
What you can do with gcx depends on how you sign in and which Grafana products or services you use. Use this page to find out what permissions you need for authentication, what each product requires, and how to fix authorization errors.
- User and service account authentication: How OAuth and service account permissions work, and the role required for OAuth sign-in.
- Permissions by product and service: Grafana roles and actions needed for dashboards, Grafana Alerting, Grafana IRM, Synthetic Monitoring, Grafana Cloud k6, SLO, and more.
- Choose Grafana Cloud access policy scopes: Scopes for the separate Grafana Cloud credential used by
gcx cloudand direct Grafana Cloud API calls. - Fix an authorization error: How to inspect your effective actions and troubleshoot exit code
3errors.
Note
These permissions apply to the current release of
gcxand can change as Grafana products and APIs evolve. For the latest requirements, refer to the documentation linked in each product section.
User and service account authentication
For commands that interact with your Grafana instance or Grafana Cloud stack, gcx uses the permissions of the Grafana identity you signed in with:
- OAuth sign-in:
gcxacts as your Grafana user. Your effective permissions are your own Grafana user permissions. OAuth sign-in doesn’t add to them, so you can’t do anything withgcxthat you can’t already do in the Grafana UI. - Service account sign-in: When you sign in with a service account token,
gcxuses the permissions assigned to that service account. Refer to Service account token for setup details. - Basic authentication and mutual TLS (mTLS): For self-managed Grafana,
gcxuses the permissions of the authenticated Grafana user or identity.
For setup details for each sign-in method, refer to Authenticate gcx.
In all cases, your Grafana user or service account needs the product-specific roles and actions listed in Permissions by product and service.
Required role for OAuth sign-in
To authorize a gcx CLI connection with OAuth, your Grafana user needs the grafana-assistant-app.tokens.gcx:access permission. The gcx User role, registered by the Grafana Assistant application, grants this permission and is assigned automatically to users with the Viewer basic role or higher.
If your default role is None, or you’re using a custom role that doesn’t grant the default plugins.app:access action, you also need to explicitly grant access to grafana-assistant-app:
{
"action": "plugins.app:access",
"scope": "plugins:id:grafana-assistant-app"
}The grafana-assistant-app.tokens.gcx:access permission only lets you create gcx tokens for your own user. It doesn’t grant access to other users’ tokens, and it doesn’t extend your existing Grafana permissions.
If gcx login fails with a Permission Required error naming the gcx User role, ask your Grafana administrator to assign you the gcx User role or a custom role that includes the grafana-assistant-app.tokens.gcx:access permission. If the role doesn’t exist on your instance, update the Grafana Assistant application to a version that includes it.
Permissions by product and service
Grant your Grafana user (for OAuth) or service account (for token authentication) a basic role that matches what you need to do, plus the product permissions listed in the following sections for each service you use.
Dashboards, folders, and data sources
Dashboards, folders, and data sources use Grafana basic roles, or custom role-based access control (RBAC) roles for scoped access.
On Grafana Cloud and Grafana Enterprise, you can use RBAC custom roles to scope query access more tightly, for example datasources:read plus datasources:query on specific data sources.
To learn more about roles and permissions for dashboards, folders, and data sources, refer to Manage dashboard permissions and Data source management.
Adaptive Telemetry
Adaptive Metrics, Adaptive Logs, Logs Archive, and Adaptive Traces commands (gcx metrics adaptive, gcx logs adaptive, gcx logs archive, and gcx traces adaptive) call Grafana Cloud APIs, so they use a Grafana Cloud credential instead of your Grafana sign-in.
Refer to Choose Grafana Cloud access policy scopes for the full list of scopes.
To learn more about roles and permissions for Adaptive Telemetry, refer to Grafana Cloud Access Policies.
Agent Observability
gcx agento11y commands use the Agent Observability plugin (grafana-agento11y-app) on your stack through your Grafana sign-in.
All Agent Observability roles also require plugins.app:access scoped to plugins:id:grafana-agento11y-app (included in the built-in roles).
To learn more about roles and permissions for Agent Observability, refer to Security and access controls.
Alerting
gcx alert commands use the Grafana Alerting APIs and require these permissions:
To learn more about roles and permissions for Grafana Alerting, refer to Configure RBAC.
Annotations
gcx annotations commands use the Grafana annotations API through your Grafana sign-in. Dashboard annotations also follow the permissions of their dashboard.
To learn more about annotation actions and scopes, refer to RBAC permissions, actions, and scopes.
Application Observability
gcx appo11y commands query your stack’s telemetry data sources and use the Application Observability plugin (grafana-app-observability-app) through your Grafana sign-in.
To learn more about roles and permissions for Application Observability, refer to Application Observability role-based access control.
Database Observability
gcx dbo11y commands query your Prometheus data source and check the Database Observability activation status on your stack through your Grafana sign-in.
To learn more about roles and permissions for Database Observability, refer to Grafana Cloud app plugin role definitions.
Fleet Management
gcx fleet commands reach Fleet Management through the Collector app on your stack, so they use your Grafana sign-in and don’t need a Grafana Cloud access policy scope. You need these Collector app permissions:
To learn more about roles and permissions for Fleet Management, refer to Role-based access control for Fleet Management.
Frontend Observability
gcx frontend commands use the Frontend Observability plugin (grafana-kowalski-app), except apply-sourcemap, which uploads directly to the Faro API using a Grafana Cloud credential. gcx frontend sessions get also queries the Loki or Pinot data source that stores your session data.
An account with only grafana-kowalski-app.apps:write can create and update apps, but can’t delete apps or source map bundles.
To learn more about roles and permissions for Frontend Observability, refer to Frontend Observability role-based access control.
Grafana Assistant
gcx assistant commands use the Grafana Assistant plugin (grafana-assistant-app) on your stack through your Grafana sign-in. The Assistant Investigation User role is included in the Editor and Admin basic roles. The Viewer basic role doesn’t include it.
Troubleshoot Assistant permission errors
If a command such as gcx assistant investigations list fails, use the error message to identify the missing permission:
- Plugin route error (for example,
plugin proxy route access denied): The error doesn’t name the missing permission. You might be missingplugins.app:accessscoped toplugins:id:grafana-assistant-app. Check your actions withgcx api /api/access-control/user/actions, and send the output to your Grafana administrator. insufficient permissionsor a named action (such asgrafana-assistant-app.investigations:read): Ask your administrator to assign you the Assistant Investigation User role.- Commands that change resources or call Model Context Protocol (MCP) servers:
gcxcan’t always tell you which permission is missing. If the error doesn’t name one, ask your administrator to review your Assistant roles.
To learn more about roles and permissions for Grafana Assistant, refer to Manage Assistant access with RBAC.
Grafana Cloud k6
gcx k6 permissions depend on whether you sign in with OAuth or a service account token. When you sign in with OAuth, commands go through the k6 plugin on your stack. When you sign in with a service account token, gcx exchanges the token with the k6 API directly and also uses a Grafana Cloud credential to look up your stack.
Refer to Choose Grafana Cloud access policy scopes for configuring the stacks:read scope.
To learn more about roles and permissions for Grafana Cloud k6, refer to Configure RBAC.
Grafana IRM
gcx irm commands go through the IRM plugin on your stack, so they use your Grafana sign-in and don’t need a Grafana Cloud credential. You need an IRM plugin role.
These core roles cover most use cases:
To grant narrower access, use the granular IRM roles for the commands you run:
OnCall personal notification rules don’t work with a service account because the server rejects service account requests. Sign in as a Grafana user instead. Refer to Manage OnCall notification rules for the permissions those commands need.
To learn more about roles and permissions for Grafana IRM, refer to Roles and permissions for Grafana IRM.
Instrumentation
gcx instrumentation commands manage Grafana Instrumentation Hub through the Collector app (grafana-collector-app) on your stack, except check, explain, and list-explanations, which inspect local configuration and documentation.
Refer to Choose Grafana Cloud access policy scopes for details on the Helm token scopes.
If gcx setup status can’t check Instrumentation, it reports the result as unknown instead of no. In JSON output, enabled is null and an error object explains why. The command exits with code 3 if authentication or authorization fails, and with code 1 for other failures.
To learn more about roles and permissions for Instrumentation, refer to Role-based access control for Fleet Management.
Knowledge Graph
gcx kg commands use the Knowledge Graph plugin (grafana-asserts-app) on your stack through your Grafana sign-in.
To learn more about roles and permissions for Knowledge Graph, refer to Grafana Cloud app plugin role definitions.
Machine Learning
gcx ml commands use the Machine Learning plugin (grafana-ml-app) on your stack through your Grafana sign-in.
To learn more about roles and permissions for Machine Learning, refer to Configure RBAC permissions.
SLO
gcx slo commands use the SLO plugin on your stack. SLO permissions follow folder permissions:
To learn more about roles and permissions for SLO, refer to Configure RBAC permissions.
Synthetic Monitoring
gcx synthetic-monitoring (aliased as gcx sm) commands go through the Synthetic Monitoring data source on your stack, using your Grafana sign-in. You need a Synthetic Monitoring plugin role:
For narrower access, use the granular roles, such as plugins:grafana-synthetic-monitoring-app:checks-reader and plugins:grafana-synthetic-monitoring-app:checks-writer, or the equivalent probes, alerts, and thresholds roles.
If gcx can’t use the data source, it calls the Synthetic Monitoring API directly. That path needs a Grafana Cloud credential to create a Synthetic Monitoring token. Refer to Choose Grafana Cloud access policy scopes.
To learn more about roles and permissions for Synthetic Monitoring, refer to Manage users and teams for Synthetic Monitoring.
Choose Grafana Cloud access policy scopes
Grafana Cloud sign-in is separate from your Grafana sign-in. It gives gcx a Grafana Cloud credential for commands that call Grafana Cloud APIs: gcx cloud commands, Adaptive Telemetry (gcx metrics adaptive, gcx logs adaptive, gcx logs archive, and gcx traces adaptive), gcx k6 with a service account token, gcx frontend apps apply-sourcemap, and Synthetic Monitoring (gcx synthetic-monitoring, aliased as gcx sm) when it calls the Synthetic Monitoring API directly. Refer to Grafana Cloud product API for how to add it.
You can sign in to Grafana Cloud in two ways:
- Grafana Cloud access policy token: Recommended for automation. The scopes you give the access policy decide which commands work.
- Grafana Cloud OAuth: The experimental browser flow, with
gcx cloud loginor the Grafana Cloud step ofgcx login. By default, it requestsprofile,stacks:read,stacks:write,stacks:delete,metrics:write,logs:write, andtraces:write. Not every Grafana Cloud product command accepts it yet. However,gcx cloud orgs listrequires it: listing your organizations needs theprofilescope, and access policy tokens can’t enumerate user organization memberships.
If you use a Grafana Cloud access policy token, scope the access policy to the commands you use. Every policy needs stacks:read, which gcx checks when you sign in and when it validates the token. Add the scopes for the products you use:
Fleet Management, IRM, and SLO commands, and direct telemetry queries such as gcx metrics query, gcx logs query, gcx traces query, and gcx profiles, don’t use the Grafana Cloud credential. They use your Grafana sign-in, either OAuth or a service account token.
If you’re not sure which scopes you need, start with a narrow policy and add scopes as commands report missing-scope errors. You can change the policy’s scopes without running gcx login again.
To learn more about Grafana Cloud access policy scopes and how to create a policy and token, refer to Grafana Cloud Access Policies and Create access policies and tokens.
Fix an authorization error
When a command fails because you’re missing a permission, it fails with Authorization failed and exit code 3. Often, the error names the action you’re missing.
To fix an authorization error:
Note the action that the error names, if any.
List the actions your user is allowed to perform:
gcx api /api/access-control/user/actionsCompare the output with the action the error names.
Send the output and the error message to your Grafana administrator. They can grant the missing action, or assign you a role that includes it.
Refer to Roles and permissions for role assignment guidance.


