Skip to main content

Grafana

Grafana is an open-source analytics and monitoring platform for visualizing time-series data from various data sources. It provides powerful dashboarding capabilities, alerting features, and supports a wide range of data sources including Prometheus, Elasticsearch, PostgreSQL, MySQL, and many others.

Authentication Types​

Grafana supports 1 authentication method:

  • API Key (Service Account Tokens) - Modern authentication using service account tokens with granular permissions
    • Pros: Secure, supports fine-grained permissions (Viewer/Editor/Admin), tokens can be revoked, multiple tokens per account, ideal for automation and API access
    • Cons: Requires Grafana 9.x or later

General Settings​

Before using the connector, you need to configure:

  • Grafana Instance URL - Your Grafana instance URL (e.g., https://yourcompany.grafana.net for Grafana Cloud or http://grafana.yourcompany.com for self-hosted)

Setting up API Key (Service Account Tokens)​

Service accounts are the recommended way to authenticate with Grafana's API. They provide secure, programmatic access with granular permissions that can be easily managed and revoked.

  1. Log in to your Grafana instance with administrator privileges

  2. Navigate to Administration → Users and access → Service Accounts (or Configuration → Service Accounts in older versions)

  3. Click Add service account

  4. Enter a name for the service account (e.g., "Webrix Integration")

  5. Select the appropriate role for the service account:

    • Viewer - Read-only access to dashboards and datasources
    • Editor - Can create and modify dashboards and datasources
    • Admin - Full administrative access (use with caution)

  6. Click Create

  7. In the service account details page, click Add service account token

  8. Enter a name for the token (e.g., "Webrix API Token")

  9. Optionally set an expiration date for the token (recommended for security)

  10. Click Generate token

  11. Important: Copy the generated token immediately - it will only be shown once

  12. In Webrix, paste the token into the API Key field

  13. Enter your Grafana Instance URL in the General Settings field

  14. Click Save Changes

tip

Store your service account token securely. If you lose it, you'll need to generate a new one. For production use, consider setting token expiration dates and rotating tokens regularly.

Common Use Cases​

Dashboard Management​

  • Programmatically create and update dashboards
  • Export dashboard configurations for backup or migration
  • Organize dashboards into folders
  • Track dashboard changes with version history

Data Source Configuration​

  • Automate datasource provisioning across environments
  • Configure connections to Prometheus, PostgreSQL, Elasticsearch, and other data sources
  • Manage datasource credentials and settings
  • Test and validate datasource connections

Alert Rule Management​

  • Create and configure alert rules for monitoring
  • Set up notification channels and routing
  • Manage alert conditions and thresholds
  • Monitor alert rule status and history

User and Organization Administration​

  • Manage user access and permissions
  • List and inspect users across organizations
  • Verify authentication and user context
  • Audit service account usage

Troubleshooting​

Permission Denied Errors​

Cause: The service account token doesn't have sufficient permissions for the requested operation.

Solution:

  1. Go to Administration → Service Accounts in Grafana
  2. Find your service account and check its assigned role
  3. If needed, update the role to a higher permission level:
    • Use Editor role for dashboard and datasource management
    • Use Admin role for user management and organization-level operations
  4. Generate a new token if the role was changed

Invalid Instance URL​

Cause: The Grafana Instance URL is incorrectly formatted or inaccessible.

Solution:

  1. Verify the URL format:
    • Grafana Cloud: https://yourcompany.grafana.net (without trailing slash)
    • Self-hosted: http://grafana.yourcompany.com or https://grafana.yourcompany.com
  2. Ensure the URL is accessible from your network
  3. Check that you're using the correct protocol (http vs https)
  4. Remove any trailing slashes or path segments from the URL

Token Expired or Revoked​

Cause: The service account token has expired or been revoked.

Solution:

  1. Go to Administration → Service Accounts in Grafana
  2. Select your service account
  3. Check the token list - expired or revoked tokens will be marked
  4. Click Add service account token to generate a new token
  5. Update the token in Webrix with the new value

Dashboard Not Found (404)​

Cause: The dashboard UID is incorrect or the dashboard has been deleted.

Solution:

  1. Use the "List Dashboards" tool to search for available dashboards
  2. Verify the dashboard UID from the search results
  3. Check that you have the correct UID format (not the numeric ID)
  4. Ensure the dashboard hasn't been moved to a different organization

Datasource Connection Failures​

Cause: The datasource URL is incorrect or the datasource is not accessible from Grafana.

Solution:

  1. Verify the datasource URL is correct and accessible
  2. For "proxy" access mode, ensure Grafana server can reach the datasource
  3. For "direct" access mode, ensure browser clients can reach the datasource
  4. Check authentication credentials in the datasource configuration
  5. Use the "Get Datasource by UID" tool to inspect the current configuration

Organization Context Issues​

Cause: Operating in the wrong organization context, especially in multi-tenant Grafana instances.

Solution:

  1. Use the "Get Current Organization" tool to verify which organization you're in
  2. Use the "List Organizations" tool to see all available organizations
  3. Ensure your service account has access to the target organization
  4. If using Grafana Cloud with multiple organizations, verify the correct instance URL

API Rate Limits​

Grafana does not enforce strict API rate limits by default, but excessive API usage may impact performance. For production use:

  • Implement reasonable delays between bulk operations
  • Use pagination when listing large numbers of resources
  • Cache results when appropriate to minimize API calls
  • Monitor your Grafana instance performance

Security Best Practices​

  1. Use Service Accounts: Always use service accounts instead of personal user tokens for automation
  2. Principle of Least Privilege: Assign the minimum required role (Viewer/Editor/Admin) for your use case
  3. Token Expiration: Set expiration dates on tokens and rotate them regularly
  4. Token Storage: Store tokens securely using environment variables or secrets management
  5. Audit Access: Regularly review service account usage and revoke unused tokens
  6. Network Security: Ensure Grafana instances are behind proper network security controls