API Keys

Each project has two API keys with different permissions. Use scoped API keys to control exactly what each key can do.

Type	Prefix	Default Scopes	Use for
Public	`gl_pk_`	`ingest:write`	Browser / client-side SDKs
Secret	`gl_sk_`	`*` (all)	Server-side, MCP, CI/CD, full API access

Scopes

API keys can be scoped to limit access. When creating a key, select only the scopes you need.

Scope	Description	Endpoints
`*`	Full access — every scope below. Default for secret keys.	All `/v1/*`
`ingest:write`	Write events / logs / spans / web vitals / errors / replay / profiles via the envelope, upload sourcemaps	`POST /v1/envelope`, `POST /v1/events`, `POST /v1/logs`, `PUT /v1/artifacts`, `POST /v1/replay/`, `POST /v1/profiles/`
`data:read`	Read anything in the project's data plane — runs through GQL (`from:logs`, `from:events`, `from:alerts`, etc.), lists artifacts, runs symbolication	`POST /v1/gql`, `GET /v1/alerts`, `GET /v1/artifacts`, `POST /v1/symbolicate`
`data:write`	Mutate the data you can read — alert rule CRUD, mute, etc.	`POST/PUT/DELETE /v1/alerts/*`
`exports:read`	List export jobs and fetch download URLs	`GET /v1/exports`
`exports:write`	Kick off an export (CSV, JSON, GDPR ZIP) — runs as a background job	`POST /v1/exports`
`ai:chat`	AI chat + debug (token-billed separately)	`POST /v1/ai/chat`, `POST /v1/ai/chat/stream`

Alerts intentionally don't have their own alerts:* scopes — they're queried via the same GQL layer as everything else (from:alerts | last:24h), so data:read already grants read access. Splitting them would be security theater. data:write covers the CRUD path.

API v1 Endpoints

All /v1/ endpoints authenticate with API keys. The project is determined from the key — no org or project IDs needed in the URL.

bash

# Query anything via GQL
curl -X POST -H "Authorization: Bearer gl_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"queries": ["from:logs severity:error | last:1h | top 10"]}' \
  https://api.goodlogs.ajaysharma.dev/v1/gql

# Send events
curl -X POST -H "Authorization: Bearer gl_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"batch": [{"event": "signup", "distinct_id": "user_1"}]}' \
  https://api.goodlogs.ajaysharma.dev/v1/events

# AI chat
curl -X POST -H "Authorization: Bearer gl_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"message": "Show me errors from the last hour"}' \
  https://api.goodlogs.ajaysharma.dev/v1/ai/chat

# List alert rules — uses data:read, same scope as everything else
curl -H "Authorization: Bearer gl_sk_..." \
  https://api.goodlogs.ajaysharma.dev/v1/alerts

Public Keys

Safe to expose in client-side JavaScript. Default scope is ingest:write only. To enable browser-side logging, toggle Allow browser logs in project settings.

Secret Keys

Full access by default (*) — can ingest, read everything, mutate alerts, run AI, and create exports. Use only in server-side code, environment variables, or CI/CD pipelines.

Important: Never expose secret keys in client-side code, Git repos, or public environments. If compromised, revoke immediately in Dashboard → API Keys and create a new one.

MCP Server Setup

The MCP server uses an API key — no JWT tokens or org/project IDs needed.

bash

# Create a key with read-only access to your data + AI chat
# Dashboard → Settings → API Keys → Create

# Configure MCP
GOODLOGS_API_KEY=gl_sk_... goodlogs-mcp

Recommended scopes for MCP: data:read, ai:chat.

Rate Limits

Rate limits are per account, per second. Exceeding the limit returns 429 Too Many Requests. The SDK handles retries with exponential backoff automatically.

Plan	Requests/sec
Free	10
Starter	20
Pro	50
Team	100

Managing Keys

Create and manage API keys in Dashboard → Settings → API Keys.

Keys are shown once at creation and stored as hashes — they cannot be retrieved later. Each key tracks its last used timestamp.

Revoking a Key

Revoke a key to disable it without deleting. A revoked key stops authenticating immediately but stays visible in your key list. You can unrevoke it at any time to re-enable it.

Deleting a Key

Deleted keys are soft-deleted with a 30-day restore window. During this period:

The key appears in the Recently Deleted section
Click Restore to bring it back and reactivate it
After 30 days, the key is permanently removed

Quota Limits

Each plan has a maximum number of API keys across all projects:

Plan	Max Keys
Free	5
Starter	10
Pro	100
Team	200

If restoring a deleted key would exceed your quota, you'll see upgrade options or can force the restore anyway.