Authentication

The Spyglasses API uses API key authentication. Both kinds of key travel in the same x-api-key header, so you only ever learn one header — but they are not interchangeable, and using the wrong one returns 401.

Which Key Do I Need?

The rule of thumb: reading one property's analytics uses the property key; anything under /api/v1/ uses the organization key.

The organization key is the right choice for automation platforms and agency workflows. It works across every client property in the organization, so one Zapier or n8n connection can serve your whole book of business rather than one credential per client. Endpoints that take a propertyId verify that the property belongs to the authenticated organization, so the key can never reach another customer's data.

API Key Format

Spyglasses API keys follow this format:

sg_XXXXXXXX-XXXX_XXXXXXXXXXXXXXXXXXXXXXXXXXXX

The sg_ prefix identifies it as a Spyglasses API key.

Finding Your Property API Key

1. Log in to your Spyglasses dashboard
2. Select your property from the sidebar
3. Navigate to Settings
4. Locate the API Key section
5. Click the copy button to copy your key

Finding Your Organization API Key

1. Log in to your Spyglasses dashboard
2. Open Organization Settings
3. Locate the API Key section
4. Click Generate API Key if you don't have one yet, then copy it

Generating a new organization key immediately invalidates the previous one. Update every integration that uses it in the same sitting.

Using Your API Key

Include your API key in the x-api-key header of every request:

curl -X GET "https://spyglasses.io/api/me" \
  -H "x-api-key: sg_YOUR_API_KEY_HERE"

Example with POST Request

For POST requests, also include the Content-Type header:

curl -X POST "https://spyglasses.io/api/analytics/ai/timeline-with-trends" \
  -H "Content-Type: application/json" \
  -H "x-api-key: sg_YOUR_API_KEY_HERE" \
  -d '{
    "propertyApiKey": "sg_YOUR_API_KEY_HERE",
    "timeRange": {
      "start": "2025-01-01T00:00:00Z",
      "end": "2025-01-31T23:59:59Z"
    },
    "granularity": "day"
  }'

Property ID vs API Key

Some endpoints require a propertyId parameter. This is different from your API key:

• API Key (sg_XXX...) - Used for authentication in the x-api-key header
• Property ID (cm9XXX...) - Used to identify which property's data you want to access

To get your property ID, call the /api/me endpoint:

curl -X GET "https://spyglasses.io/api/me" \
  -H "x-api-key: sg_YOUR_API_KEY_HERE"

The response includes your propertyId:

{
  "propertyId": "cm9ovvnnc0001wjubh0en0cpe",
  "domain": "example.com",
  ...
}

Security Best Practices

Do

• Store API keys in environment variables
• Use server-side code to make API requests
• Rotate keys if you suspect they've been compromised

Don't

• Commit API keys to version control
• Expose API keys in client-side JavaScript
• Share API keys in public forums or documentation

Regenerating Your API Key

If your API key is compromised, you can regenerate it:

1. Go to your property Settings
2. Find the API Key section
3. Click Regenerate API Key
4. Update your integrations with the new key