Skip to main content

​
Get Your API Key

Authentication with Surfa is simple - you just need an API key.
1

Sign up

Create a free account at surfa.dev
2

Access your dashboard

Go to your dashboard
3

Create an API key

Navigate to Settings → API Keys and click “Create New Key”
4

Copy your key

Your key will start with sk_live_ - copy it and store it securely
Success! You now have your API key. Keep it secure and never commit it to Git.

​
Using Your API Key

Building your own integration? See the API Reference for endpoint details, payload schemas, and request/response examples.

​
For SDK (Tracking Events)

Use your API key when initializing the Surfa SDK: 
from surfa_ingest import SurfaClient
import os

analytics = SurfaClient(
    ingest_key=os.getenv("SURFA_INGEST_KEY"),
    api_url=os.getenv("SURFA_API_URL", "https://surfa-web.vercel.app")
)
Set as environment variable: 
export SURFA_INGEST_KEY=sk_live_your_key_here
export SURFA_API_URL=https://surfa-web.vercel.app
Or add to your .env file: 
SURFA_INGEST_KEY=sk_live_your_key_here
SURFA_API_URL=https://surfa-web.vercel.app

​
For MCP Server (Querying Analytics)

Add your API key to Claude Desktop config: macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 
{
  "mcpServers": {
    "surfa": {
      "command": "/path/to/uv",
      "args": ["--directory", "/path/to/surfa-mcp", "run", "surfa-mcp"],
      "env": {
        "SURFA_API_KEY": "sk_live_your_key_here",
        "SURFA_API_URL": "https://surfa-web.vercel.app"
      }
    }
  }
}

​
API Key Types

Surfa uses different key prefixes for different environments:
PrefixEnvironmentUse Case
sk_live_ProductionLive data, production MCP servers
sk_test_TestingDevelopment and testing
Test keys are isolated from production data. Use them for development and CI/CD.

​
Security Best Practices

Bad:
# ❌ Don't do this!
analytics = SurfaClient(ingest_key="sk_live_abc123...")
Good:
# ✅ Use environment variables
analytics = SurfaClient(ingest_key=os.getenv("SURFA_INGEST_KEY"))
Add .env to your .gitignore:
.env
.env.local
Store keys in environment variables, not in code:Development:
# .env file
SURFA_INGEST_KEY=sk_live_your_key
Production: Set environment variables in your deployment platform:
  • Vercel: Settings → Environment Variables
  • Railway: Variables tab
  • Fly.io: fly secrets set SURFA_INGEST_KEY=...
Rotate your API keys periodically for security:
  1. Create a new key in dashboard
  2. Update environment variables
  3. Deploy changes
  4. Delete old key
Keep the old key active for 24 hours during rotation to avoid downtime.
Use different keys for different environments:
  • Production: sk_live_prod_abc123
  • Staging: sk_live_staging_xyz789
  • Development: sk_test_dev_123456
This isolates data and makes it easier to track issues.

​
Workspace Isolation

Each API key is tied to a specific workspace. This means:
  • ✅ Data isolation - You only see your workspace’s data
  • ✅ Multi-tenant safe - No cross-workspace leakage
  • ✅ Team collaboration - Share workspace access with team members
Want to track multiple projects? Create separate workspaces in your dashboard.

​
Troubleshooting

Possible causes:
  1. Key is incorrect or has typos
  2. Key was deleted from dashboard
  3. Using test key in production (or vice versa)
Solution:
  • Verify key in dashboard
  • Check environment variables are set correctly
  • Ensure no extra spaces or quotes
Possible causes:
  1. API key not included in request
  2. Environment variable not set
  3. Key expired or revoked
Solution:
# Verify key is loaded
import os
print(os.getenv("SURFA_INGEST_KEY"))  # Should print your key
Check:
  1. API key is correct
  2. API URL is correct (https://surfa-web.vercel.app)
  3. No firewall blocking outbound requests
  4. Events are being tracked (check logs)
Debug:
import logging
logging.basicConfig(level=logging.DEBUG)

# You'll see API requests in logs
analytics.track({...})

​
Rate Limits

The Ingest API is rate limited to prevent abuse:
  • 1,000 events per minute per API key
  • 60 second sliding window
If you exceed the rate limit, requests will return 429 Too Many Requests. The SDK automatically retries with exponential backoff.
The MCP Query API (for Claude Desktop) currently has no rate limits.

​
Next Steps

Quickstart Guide

Start tracking events in 5 minutes

API Reference

Complete API documentation with examples

Privacy & PII

Learn what data Surfa tracks

MCP Server Setup

Query analytics with Claude Desktop