--- title: "Authenticate gcx | Grafana documentation" description: "Authenticate gcx gcx supports four ways to authenticate to a Grafana instance or stack: OAuth - Grafana Cloud only: Browser-based sign-in with gcx login. Recommended for interactive use. The tokens are user-scoped: every request runs with your own identity and RBAC permissions, so you can’t access anything through gcx that you can’t already access in the Grafana UI. Refer to Required role for OAuth sign-in for the permission this flow needs. Service account token: Works for Grafana Cloud and on-premises instances, and is the recommended method for CI and other non-interactive environments. Refer to Grafana service accounts for how to create one. Basic authentication - Self-managed Grafana: Username and password. Use this only when service accounts aren’t available. mTLS: A client certificate and key for instances behind an identity-aware proxy. Configure the grafana.tls fields or corresponding TLS environment variables. No Grafana Cloud account yet If you don’t have a Grafana account, run:" --- > For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt). # Authenticate `gcx` `gcx` supports four ways to authenticate to a Grafana instance or stack: - [OAuth - Grafana Cloud only](https://grafana.com/docs/grafana/v13.3/ai-tools/grafana-cli/gcx/authentication/#browser-based-oauth-cloud-only-recommended): Browser-based sign-in with `gcx login`. Recommended for interactive use. The tokens are user-scoped: every request runs with your own identity and RBAC permissions, so you can’t access anything through `gcx` that you can’t already access in the Grafana UI. Refer to [Required role for OAuth sign-in](https://grafana.com/docs/grafana/v13.3/ai-tools/grafana-cli/gcx/authentication/#required-role-for-oauth-sign-in) for the permission this flow needs. - [Service account token](https://grafana.com/docs/grafana/v13.3/ai-tools/grafana-cli/gcx/authentication/#service-account-token): Works for Grafana Cloud and on-premises instances, and is the recommended method for CI and other non-interactive environments. Refer to [Grafana service accounts](https://grafana.com/docs/grafana/latest/administration/service-accounts/) for how to create one. - [Basic authentication - Self-managed Grafana](https://grafana.com/docs/grafana/v13.3/ai-tools/grafana-cli/gcx/authentication/#basic-authentication-self-managed-grafana): Username and password. Use this only when service accounts aren’t available. - mTLS: A client certificate and key for instances behind an identity-aware proxy. Configure the `grafana.tls` fields or corresponding TLS [environment variables](https://grafana.com/docs/grafana/v13.3/ai-tools/grafana-cli/gcx/authentication/#environment-variables). ## No Grafana Cloud account yet If you don’t have a Grafana account, run: Bash ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy ```bash gcx signup ``` `gcx` opens the Grafana Cloud sign-up page. After you create the account, verify your email, create your first stack, and approve “Connect gcx”, the browser returns to gcx, which saves the connection. If you already have an account but no stack URL at hand, run `gcx login` and leave the server empty, or `gcx login --cloud --oauth` from a script or agent. Refer to [First-time Grafana Cloud login](https://github.com/grafana/gcx/blob/main/docs/reference/login.md#first-time-grafana-cloud-login) for more details. ## Browser-based OAuth (Cloud-only, recommended) Best for day-to-day use on Cloud stacks, you can use this interactive option: Bash ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy ```bash gcx login my-stack --server https://my-stack.grafana.net ``` If OAuth doesn’t suit your setup, pick “Service account token” at the prompt. This flow: 1. Opens a browser for OAuth. 2. Saves the access token. 3. Saves the access token, refresh token, and proxy endpoint to the `my-stack` context’s named stack entry, and makes the context current. 4. `gcx` stops before the browser flow when the current process cannot write to the OS credential store. Note that agent users must approve the same command outside the sandbox. Refer to [Keychain credential storage](https://grafana.com/docs/grafana/v13.3/ai-tools/grafana-cli/gcx/keychain). ### 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’ll also need to explicitly grant access to `grafana-assistant-app`: JSON ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy ```json { "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 to use Assistant investigations 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 with `Authorization failed` and exit code 3, your Grafana user is missing a permission. The error message tells you which one: Expand table | If the error mentions | You’re missing | How to fix it | |---------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------| | A plugin route, for example `plugin proxy route access denied` | Access to the Assistant app: `plugins.app:access` scoped to `plugins:id:grafana-assistant-app` | Ask your Grafana administrator to grant this permission. | | `insufficient permissions`, or a named action such as `grafana-assistant-app.investigations:read` | Permission to read investigations: `grafana-assistant-app.investigations:read` | Ask your administrator to assign you the **Assistant Investigation User** role. | #### Check which permissions you have To list the actions your user is allowed to perform, run: Bash ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy ```bash gcx api /api/access-control/user/actions ``` Send the output to your Grafana administrator along with the error message. Refer to [roles and permissions](https://grafana.com/docs/grafana/latest/administration/roles-and-permissions/) for role assignment guidance. > Note > > `gcx setup status` doesn’t check Assistant access, so a passing status check doesn’t mean Assistant commands will work. #### See 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. #### 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. ### Permissions to check instrumentation status `gcx setup status` and `gcx instrumentation clusters list` check Kubernetes monitoring through the Collector app. To run them, your Grafana user needs both of these permissions: - `grafana-collector-app:read` - `grafana-collector-app:admin` If you’re missing one, the command fails with `Authorization failed` and exit code 3. To list the actions your user is allowed to perform, refer to [Check which permissions you have](https://grafana.com/docs/grafana/v13.3/ai-tools/grafana-cli/gcx/authentication/#check-which-permissions-you-have). #### Read the status when a check fails `gcx setup status` reports `true` or `false` for each product it can check. `false` means `gcx` checked and the product isn’t set up. If `gcx` can’t check a product, for example because of a permissions error, the state is **unknown**. Unknown can appear as `unknown` in a text table, or as `enabled: null` in JSON and YAML. The `fleet-management` row also shows unknown when `gcx` can’t read the state of the Collector app, because its status depends on that app. #### Use status checks in scripts and agents When a check fails, the rest of the status document is still returned, with the same `type`, `schema_version`, and `products` fields. You can parse it as usual and treat `null` values as unknown. To get the failure details in the output itself, run the command in agent mode or with `--json`. The output then includes an `error` object with these fields: Expand table | Field | Description | |--------------------------------------|-----------------------------------------------| | `summary` | A short description of the failure. | | `exitCode` | The exit code the command returns. | | `details`, `suggestions`, `docsLink` | Optional. Present when `gcx` has more to say. | These options remove the error object from the filtered output, so `gcx` also writes the error text to `stderr`: - `-o yaml`, and `-o json` outside agent mode. - `--jq`. - `--json ` when the field list doesn’t include `error`. - `--json list` #### Exit codes `gcx setup status` is a read-only check, so it never exits with code 4. Expand table | Exit code | Meaning | |-----------|----------------------------------------------------------------------------------------------------------| | 3 | A probe failed with HTTP 401 or 403. Check your permissions. | | 1 | Any other probe failed, for example HTTP 500. This applies even if the other products returned a result. | ### Grafana Cloud product API Grafana Cloud platform APIs use a separate credential stored in a named Cloud entry in addition to the Grafana instance auth. For automation, log in with a [Cloud Access Policy token](https://grafana.com/docs/grafana-cloud/account-management/authentication-and-permissions/access-policies/), which has the widest command compatibility. A CAP supports many Cloud management operations, but cannot enumerate user organisation memberships: Bash ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy ```bash gcx login my-stack --server https://my-stack.grafana.net --token glsa_xxx --cloud-token glc_xxx --yes ``` You can also add Cloud access later by re-running `gcx login` against the same context. The interactive Cloud step can keep the existing CAP or unexpired OAuth credential, accept a new CAP, run the experimental browser-based Cloud OAuth flow, or skip Cloud functionality. ### Direct OAuth on Cloud Direct Cloud OAuth is available through `gcx cloud login` or the interactive Cloud step of `gcx login`, but remains experimental and is not yet accepted by every Cloud product command. OAuth entries retain token, expiry, granted scopes, and a coherent OAuth/API endpoint pair. Bash ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy ```bash gcx cloud login --context my-stack ``` To list your Cloud organisation memberships (slugs and roles): Bash ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy ```bash gcx cloud login --context my-stack gcx cloud orgs list --context my-stack ``` Default Cloud logins include `profile` alongside stack-management scopes. Run again `login` for existing credentials. `--scope profile` replaces the scope set, so use the default login to retain stack access. If `GRAFANA_CLOUD_TOKEN` or `cloud..token` is set, unset it when using browser OAuth for organisation listing: access-policy tokens take precedence over OAuth tokens. The command uses the selected context’s Cloud API endpoint, including dev and ops environments. Membership is not a guarantee of stack-creation permission. This differs from `gcx api /api/orgs`, which targets organisations inside a Grafana instance. ### Specify your org To specify the organisation slug when creating a stack: Bash ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy ```bash gcx cloud stacks create --org example-org --name my-stack --slug mystack --region us --dry-run ``` Dry runs show the creation request. Review the preview, then omit `--dry-run` to create the stack. Creation defaults to YAML with `name`, `orgSlug`, `slug`, `status` and `url`. Use `stacks get ` for full details. `gcx` derives the Cloud stack slug from `--server` when possible. Set it explicitly only for custom domains where gcx cannot derive it: Bash ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy ```bash gcx config set stacks.my-stack.slug your-stack-slug ``` Both `stacks create` and `stacks list` require `--org `. ### Custom environments You don’t need to set Cloud endpoints for `grafana.com` as `gcx` defaults to `https://grafana.com`. For a custom environment, authenticate and store a coherent OAuth/API destination pair: supplying one endpoint to a login command uses it for both operations unless you explicitly supply both to `gcx cloud login`. Changing a named entry’s `api-url` or `oauth-url` invalidates its old credential, so re-authenticate after the edit. ## Service account token Service account tokens work for Cloud or self-managed Grafana, and are useful for CI automation: Bash ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy ```bash gcx login my-grafana --server https://your-instance.grafana.net --token glsa_xxx --yes ``` Use a [Grafana service account token](https://grafana.com/docs/grafana/latest/administration/service-accounts/) with a role matching what the token needs to do: **Viewer** is enough for querying (metrics, logs, traces, profiles) and reading dashboards or folders; **Editor** covers pushing and editing dashboards and folders; managing datasource configuration needs **Admin**. On Grafana Cloud and Enterprise, RBAC custom roles can scope query access tighter (for example `datasources:read` plus `datasources:query` on specific datasources). On-premises stacks can also use basic authentication or configured mTLS client certificates. ## Basic authentication (self-managed Grafana) If you’re using self-managed Grafana, you can also use basic auth, which prompts for a password without echoing it: Bash ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy ```bash gcx login my-grafana --server https://grafana.example.com --basic-auth --user admin ``` For automation, supply `GRAFANA_PASSWORD` and add `--yes`. Refer to [Basic authentication](https://grafana.com/docs/reference/login/#basic-authentication) for credential storage, auth switching, and validation behaviour. ## Environment variables For CI/CD or if you’re using an AI agent, you can authenticate using environment variables: Bash ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy ```bash export GRAFANA_SERVER="https://your-instance.grafana.net" export GRAFANA_TOKEN="your-service-account-token" export GRAFANA_CLOUD_TOKEN="your-cloud-access-policy-token" # Optional: only needed if gcx cannot derive the stack slug from GRAFANA_SERVER. export GRAFANA_CLOUD_STACK="your-stack-slug" ``` Environment variables resolve at every command invocation, so you can run `gcx` commands directly without a prior `gcx login`. ## Auto-discovered repositories For safety, an auto-discovered repository `.gcx.yaml` cannot attach runtime tokens, prompted login credentials, or external mTLS keypairs to destinations the file supplies. If you want that file to own credentials or direct provider endpoints you need to authorize it explicitly: Bash ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy ```bash gcx login --config .gcx.yaml # or GCX_CONFIG=.gcx.yaml gcx login ``` Refer to [Credentials in auto-discovered repositories](https://grafana.com/docs/grafana/v13.3/ai-tools/grafana-cli/gcx/configuration#credentials-in-auto-discovered-repositories) for more details. ## Verify your configuration Run `gcx config check` to check your configuration. Refer to the [login reference](https://github.com/grafana/gcx/blob/main/docs/reference/login.md) for the full guide, including re-authentication, environment-variable setup, and troubleshooting for common errors. ## Troubleshooting ### Data source authentication failures Data source-managed rule commands such as `gcx alert ruler groups list` exit with code 3 when authentication fails. Run `gcx datasources health ` to see the data source health. - The health check uses a different API path and doesn’t establish that ruler access works. - To find the UID, use `gcx datasources list -o json`. Inspect the data source with `gcx datasources get -o json` and check its credentials and ruler configuration in Grafana.