Authentication

The Spyglasses API uses API key authentication. Each property has a unique API key that grants access to that property'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 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

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