Authentication

GoodMetrics REST API requests use dashboard-issued API keys.

REST API keys

Create an API key in the GoodMetrics dashboard. The secret key is shown once when created, so store it securely before leaving the page.

Bearer API keys must:

• Be active and not revoked.
• Be unexpired, if an expiry was configured.
• Belong to a user with access to the requested site.

Send the key with each REST API request:

Authorization: Bearer YOUR_API_KEY

Public route

REST API analytics requests use the public site GMID route: https://data.goodmetrics.io/{gmID}/events/{resource}. Realtime requests can be made without query parameters. Reporting requests use flat query parameters such as start, end, country_is, sort_by, and dir.

The API resolves {gmID} to the internal site and checks the requesting key owner’s organization and site permissions.

Example authenticated request:

curl

curl "https://data.goodmetrics.io/{gmID}/events/realtime/visitors" \
  -H "Authorization: Bearer YOUR_API_KEY"

Node

const gmID = '{gmID}';
const apiKey = 'YOUR_API_KEY';
const response = await fetch(`https://data.goodmetrics.io/${gmID}/events/realtime/visitors`, {
  headers: {
    Authorization: `Bearer ${apiKey}`
  }
});

console.log(await response.json());

Python

import json
import urllib.request

gm_id = "{gmID}"
api_key = "YOUR_API_KEY"
request = urllib.request.Request(
    f"https://data.goodmetrics.io/{gm_id}/events/realtime/visitors",
    headers={"Authorization": f"Bearer {api_key}"},
)

with urllib.request.urlopen(request) as response:
    print(json.load(response))

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

class GoodMetricsExample {
  public static void main(String[] args) throws Exception {
    var gmID = "{gmID}";
    var apiKey = "YOUR_API_KEY";
    var url = "https://data.goodmetrics.io/" + gmID + "/events/realtime/visitors";

    var request = HttpRequest.newBuilder()
      .uri(URI.create(url))
      .header("Authorization", "Bearer " + apiKey)
      .GET()
      .build();

    var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
  }
}

C#

using System;
using System.Net.Http;
using System.Net.Http.Headers;

var gmID = "{gmID}";
var apiKey = "YOUR_API_KEY";
var url = $"https://data.goodmetrics.io/{gmID}/events/realtime/visitors";

using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Get, url);
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);

using var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());

PHP

<?php
$gmID = "{gmID}";
$apiKey = "YOUR_API_KEY";
$url = "https://data.goodmetrics.io/{$gmID}/events/realtime/visitors";

$context = stream_context_create([
    "http" => [
        "method" => "GET",
        "header" => "Authorization: Bearer {$apiKey}\r\n",
    ],
]);

$response = file_get_contents($url, false, $context);
echo $response;

Go

package main

import (
  "fmt"
  "io"
  "net/http"
)

func main() {
  gmID := "{gmID}"
  apiKey := "YOUR_API_KEY"

  request, _ := http.NewRequest(
    "GET",
    "https://data.goodmetrics.io/"+gmID+"/events/realtime/visitors",
    nil,
  )
  request.Header.Set("Authorization", "Bearer "+apiKey)

  response, _ := http.DefaultClient.Do(request)
  defer response.Body.Close()

  body, _ := io.ReadAll(response.Body)
  fmt.Println(string(body))
}

MCP OAuth

MCP clients use OAuth sign-in and consent instead of API keys. Connect an OAuth-capable MCP client to:

https://data.goodmetrics.io/mcp

The client discovers the GoodMetrics authorization service automatically and opens a browser. Sign in to GoodMetrics, review the requested analytics:read permission, and approve access. See the MCP Server reference for protocol and OAuth details.

Read-only requests

REST API key requests support GET analytics requests only. MCP uses POST for JSON-RPC tool calls, but every exposed tool is read-only.

Neither interface creates, updates, or deletes dashboard resources.

Common authentication errors

Interface	Problem	Common fix
REST API	API key is missing, invalid, revoked, expired, or lacks site access.	Check the bearer header, key status, and user permissions.
MCP	Authorization was denied, expired, revoked, or completed with the wrong account.	Reconnect the server and approve access with the intended GoodMetrics account.
Either	Rate limit exceeded.	Retry later and reduce request frequency.

Security

Keep REST API keys server-side whenever possible. If a key is exposed, revoke it in the dashboard and create a replacement.

For MCP, review the client name and analytics:read permission before approving access. Revoke the connection when you no longer use that client.