Authentication

Get Your API Key

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

Create a free account at surfa.dev

Access your dashboard

Go to your dashboard

Create an API key

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

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:

Prefix	Environment	Use Case
`sk_live_`	Production	Live data, production MCP servers
`sk_test_`	Testing	Development and testing

Test keys are isolated from production data. Use them for development and CI/CD.

Security Best Practices

Never commit keys to Git

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

Use environment variables

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 keys regularly

Rotate your API keys periodically for security:

Create a new key in dashboard
Update environment variables
Deploy changes
Delete old key

Keep the old key active for 24 hours during rotation to avoid downtime.

Use separate keys per environment

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

'Invalid API key' error

Possible causes:

Key is incorrect or has typos
Key was deleted from dashboard
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

'Unauthorized' error

Possible causes:

API key not included in request
Environment variable not set
Key expired or revoked

Solution:

# Verify key is loaded
import os
print(os.getenv("SURFA_INGEST_KEY"))  # Should print your key

Events not appearing in dashboard

Check:

API key is correct
API URL is correct (https://surfa-web.vercel.app)
No firewall blocking outbound requests
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

Getting Started

MCP Server

Guides

Get Your API Key

Using Your API Key

For SDK (Tracking Events)

For MCP Server (Querying Analytics)

API Key Types

Security Best Practices

Workspace Isolation

Troubleshooting

Rate Limits

Next Steps

Quickstart Guide

API Reference

Privacy & PII

MCP Server Setup

​Get Your API Key

​Using Your API Key

​For SDK (Tracking Events)

​For MCP Server (Querying Analytics)

​API Key Types

​Security Best Practices

​Workspace Isolation

​Troubleshooting

​Rate Limits

​Next Steps

Quickstart Guide

API Reference

Privacy & PII

MCP Server Setup

Get Your API Key

Using Your API Key

For SDK (Tracking Events)

For MCP Server (Querying Analytics)

API Key Types

Security Best Practices

Workspace Isolation

Troubleshooting

Rate Limits

Next Steps