Roles and permissions
What you can do with gcx depends on how you sign in. Use this page to find out which permissions you need for each sign-in method, and how to fix authorization errors.
- OAuth sign-in:
gcxuses your own Grafana user permissions. - Service account sign-in:
gcxuses the permissions of the service account. - Grafana Cloud sign-in: a separate credential for Grafana Cloud commands, such as
gcx cloud, scoped by an access policy.
Grant permissions for OAuth sign-in
When you sign in with OAuth, gcx acts 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 with gcx that you can’t already do in the Grafana UI.
To use a product through gcx, your user needs the same permissions that a service account would need. Refer to Grant permissions to a service account for the permissions each product needs.
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 basic role Viewer 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.
Grant permissions to a service account
When you sign in with a service account token, gcx uses the permissions of the service account. Grant the service account a role that matches what it needs to do, and add the product permissions listed in this section for the products you use.
Dashboards, folders, and data sources
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.
Alerting
gcx alert commands use the Grafana alerting APIs. The service account needs these permissions:
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 Cloud Access Policy scope. The service account needs these Collector app permissions:
Looking up your stack’s details through the Collector app only needs the Viewer role.
gcx instrumentation clusters list checks Kubernetes monitoring through the Collector app, so it needs both grafana-collector-app:read and grafana-collector-app:admin.
Grafana Assistant
The Assistant Investigation User role is included in the Editor and Admin basic roles. Viewers don’t have it.
If an Assistant command such as gcx assistant investigations list fails, use the error message to find the missing permission:
View investigations created by alerts and webhooks
Investigations that start automatically, for example from an alert or an IRM webhook, need an additional permission: grafana-assistant-app.investigations.system:read. Without it, those investigations don’t appear in your list.
Troubleshoot other Assistant commands
For commands that change things, such as creating investigations, or that call MCP servers, gcx can’t always tell you which permission is missing. If the error doesn’t name one, ask your administrator to review your Assistant roles.
Frontend Observability
The gcx frontend apps commands that change apps need these Frontend Observability permissions:
A user with only grafana-kowalski-app.apps:write can create and update apps, but can’t delete apps or source map bundles.
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. The service account needs an IRM plugin role.
These core roles cover most use:
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: 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.
Synthetic Monitoring
gcx sm commands go through the Synthetic Monitoring data source on your stack, using your Grafana sign-in. The service account needs 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.
Grafana Cloud k6
When you sign in with OAuth, gcx k6 commands go through the k6 plugin on your stack. Your user needs one of these k6 plugin roles:
When you sign in with a service account token, gcx exchanges the token with the k6 API directly. The service account needs the Admin basic role, and you also need a Grafana Cloud credential with the stacks:read scope, which gcx uses to look up your stack.
SLO
gcx slo commands use the SLO plugin on your stack. SLO permissions follow folder permissions:
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, such as managing stacks, plus k6 (gcx k6) with a service account token, and Synthetic Monitoring (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:
- 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.
If you use a Cloud Access Policy token, scope the access policy to the commands you use:
stacks:readis required. It resolves your stack and is checked when you sign in and whengcxvalidates the token.- Add the scopes for the products you use:
Fleet Management, IRM, and SLO commands, and signal queries such as gcx metrics, gcx logs, gcx traces, 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.
Refer to Create access policies for how to create the policy and token.
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.
Was this page helpful?
Related resources from Grafana Labs
