Documentation Grafana documentation AI tools gcx CLI gcx CLI Authenticate gcx

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:

Bash Copy

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 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

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.

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

{
  "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:

Check which permissions you have

To list the actions your user is allowed to perform, run:

Bash Copy

gcx api /api/access-control/user/actions

Send the output to your Grafana administrator along with the error message. Refer to roles and permissions for role assignment guidance.

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.

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:

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 <fields> 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.

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, which has the widest command compatibility. A CAP supports many Cloud management operations, but cannot enumerate user organisation memberships:

Bash Copy

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

gcx cloud login --context my-stack

To list your Cloud organisation memberships (slugs and roles):

Bash Copy

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.<entry>.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

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 <slug> 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

gcx config set stacks.my-stack.slug your-stack-slug

Both stacks create and stacks list require --org <slug>.

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

gcx login my-grafana --server https://your-instance.grafana.net --token glsa_xxx --yes

Use a Grafana service account token 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

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 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

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

gcx login --config .gcx.yaml
# or
GCX_CONFIG=.gcx.yaml gcx login

Refer to Credentials in auto-discovered repositories for more details.

Verify your configuration

Run gcx config check to check your configuration.

Refer to the login reference 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 <uid> 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 <uid> -o json and check its credentials and ruler configuration in Grafana.