Documentationbreadcrumb arrow Grafana Cloudbreadcrumb arrow AI toolsbreadcrumb arrow gcx CLIbreadcrumb arrow Authenticate gcx
Grafana Cloud Enterprise Open source

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

Best for day-to-day use on Cloud stacks, you can use this interactive option:

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.

To sign in with OAuth, your Grafana user needs the gcx User role. Refer to Required role for OAuth sign-in. For the permissions other gcx commands need, refer to Roles and permissions.

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 
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 
gcx cloud login --context my-stack

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

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.<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 
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 
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 
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 data source 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 data sources). 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 
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 
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 
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.