Authentication

graph8 has three authentication methods depending on how you’re integrating:

Method	Use case	Where to get it
API Key	REST API, CLI (server-side), SDK server features	Settings > MCP & API > API tab
Write Key	SDK client-side (tracking, visitor ID, forms, widgets)	Settings > MCP & API > tracking snippet
OAuth	MCP Server (Claude.ai, Claude Desktop, Cursor)	Automatic - paste URL and sign in

Which key do I need?

• Building a browser app? Use the JavaScript SDK with a write key (g8.init({ writeKey }))
• Building a server/script? Use the REST API or CLI with an API key
• Using an AI agent? Use the MCP Server with OAuth (no key needed)

The Developer API authenticates requests using organization API keys. JWT tokens are not accepted — use an API key for all programmatic access.

Creating an API Key

1. Go to Settings -> API in your graph8 workspace
2. Click Create API Key
3. Enter a name (e.g., “CRM Sync” or “Data Export”)
4. Optionally set an expiration (1-365 days)
5. Copy the key immediately — it’s only shown once

Tip

Store your API key in an environment variable or secrets manager. You cannot retrieve it after closing the creation dialog.

Using Your API Key

Include the key in the Authorization header with the Bearer prefix:

cURL

export API_KEY="your_api_key_here"

curl "https://be.graph8.com/api/v1/contacts" \
  -H "Authorization: Bearer $API_KEY"

Python

import requests

API_KEY = "your_api_key_here"
BASE_URL = "https://be.graph8.com/api/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

response = requests.get(f"{BASE_URL}/contacts", headers=HEADERS)
print(response.json())

TypeScript

const API_KEY = "your_api_key_here";
const BASE_URL = "https://be.graph8.com/api/v1";

const response = await fetch(`${BASE_URL}/contacts`, {
  headers: { Authorization: `Bearer ${API_KEY}` }
});

const data = await response.json();
console.log(data);

Key Characteristics

Property	Details
Scope	Organization-level — access to all data in your org
Format	Opaque token (not a JWT)
Expiration	Optional, 1-365 days from creation
Rotation	Delete and create a new key, or use the Rotate button in Settings
Rate Limit	200 requests/minute, 10 requests/second

Note

API keys inherit the organization scope automatically — no X-Org-Id header is needed.

Authentication Errors

Status	Meaning	Fix
401	Missing or invalid Authorization header	Check your API key is correct
401	JWT token provided instead of API key	Use an org API key, not a browser session token
401	API key not associated with an organization	Ensure the key was created in Settings -> API
429	Rate limit exceeded	Wait and retry with backoff (see Rate Limits)

Example Error Response

{
  "detail": "Missing Authorization header. Use: Authorization: Bearer <api_key>"
}

Security Best Practices

Do:

• Store keys in environment variables or a secrets manager
• Use separate keys for development and production
• Set expiration dates on keys
• Rotate keys periodically
• Delete unused keys promptly

Don’t:

• Commit keys to version control
• Share keys via email or chat
• Expose keys in frontend JavaScript or client-side code
• Log keys in application output

Caution

If you suspect a key has been compromised, delete it immediately in Settings -> API and create a new one.