Authentication

The TopSnapp API supports two authentication methods:

1. Session Cookies - Automatically used when making requests from the TopSnapp web application
2. API Keys - For integrations, AI agents, and programmatic access

This guide focuses on API key authentication, which is the recommended method for external integrations.

Generating API Keys

Step 1: Navigate to Settings

1. Log in to your TopSnapp account
2. Click on your profile in the top right
3. Select Settings
4. Navigate to the Integrations tab

Step 2: Create a New Key

1. Click Generate New Key
2. Enter a descriptive name (e.g., "Claude Desktop", "Production Server", "ChatGPT")
3. Click Generate Key

Step 3: Save Your Key

Important: Your API key will only be shown once. Copy it immediately and store it securely.

topsnapp_sk_VmFmDvOis7H5ad5Ux3QnS8YU5kTQJ0JnlJ0LtXSPQyLdN9na

Step 4: Use Your Key

Include your API key in the Authorization header of all requests:

curl https://www.topsnapp.com/api/snaps \
  -H "Authorization: Bearer topsnapp_sk_your_key_here"

API Key Format

TopSnapp API keys follow this format:

topsnapp_sk_<48-character-random-string>

• Prefix: topsnapp_sk_ identifies the platform and key type
• Random String: 48 characters of base64url-encoded random data (288 bits of entropy)
• Storage: Keys are hashed with bcrypt before storage (never stored in plaintext)

Security Best Practices

Treat API Keys Like Passwords

• ✅ Store keys in environment variables
• ✅ Use separate keys for development and production
• ✅ Rotate keys regularly
• ✅ Revoke unused keys immediately
• ❌ Never commit keys to version control
• ❌ Never share keys in public channels
• ❌ Never hard-code keys in your source code

Example: Environment Variables

# .env (add to .gitignore)
TOPSNAPP_API_KEY=topsnapp_sk_your_key_here

// In your application
const apiKey = process.env.TOPSNAPP_API_KEY;

Managing API Keys

Viewing Your Keys

Navigate to Settings → Integrations to see all your active API keys. You'll see:

• Name - The descriptive name you provided
• Key Prefix - First 20 characters (e.g., topsnapp_sk_VmFmDvO...)
• Created - When the key was generated
• Last Used - Last time the key was used for authentication

Revoking Keys

To revoke a key:

1. Navigate to Settings → Integrations
2. Find the key you want to revoke
3. Click the trash icon
4. Confirm revocation

Important: Revoking a key is immediate and cannot be undone. Any applications using that key will immediately lose access.

Key Limits

• Maximum 10 API keys per user
• Keys do not expire automatically
• Keys have the same permissions as your user account

Permissions

API keys inherit all permissions from your user account:

• ✅ Create, read, update, and delete your own snaps
• ✅ Access snaps shared with your workspace/organization
• ✅ Manage cards and content within your snaps
• ❌ Cannot access other users' private snaps
• ❌ Cannot perform admin actions (unless you're an admin)

Integration Examples

Claude Desktop (MCP Server)

{
  "mcpServers": {
    "topsnapp": {
      "command": "npx",
      "args": ["-y", "@topsnapp/mcp-server"],
      "env": {
        "TOPSNAPP_API_KEY": "topsnapp_sk_your_key_here"
      }
    }
  }
}

cURL

export TOPSNAPP_API_KEY="topsnapp_sk_your_key_here"

curl https://www.topsnapp.com/api/snaps \
  -H "Authorization: Bearer $TOPSNAPP_API_KEY"

JavaScript/TypeScript

const API_KEY = process.env.TOPSNAPP_API_KEY;
const BASE_URL = 'https://www.topsnapp.com/api';

async function listSnaps() {
  const response = await fetch(`${BASE_URL}/snaps`, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
    },
  });

  const data = await response.json();
  return data.snaps;
}

Python

import os
import requests

API_KEY = os.environ['TOPSNAPP_API_KEY']
BASE_URL = 'https://www.topsnapp.com/api'

def list_snaps():
    response = requests.get(
        f'{BASE_URL}/snaps',
        headers={
            'Authorization': f'Bearer {API_KEY}',
            'Content-Type': 'application/json',
        }
    )
    return response.json()['snaps']

Troubleshooting

401 Unauthorized

If you receive a 401 error:

1. Check that your API key is correct (including the topsnapp_sk_ prefix)
2. Ensure the Authorization header is properly formatted: Bearer topsnapp_sk_...
3. Verify the key hasn't been revoked in Settings → Integrations
4. Check that the key was copied completely (all 68 characters)

403 Forbidden

You're authenticated but don't have permission to access the resource. This usually means:

• You're trying to access another user's private snap
• You're attempting an admin operation without admin privileges

Next Steps

• Explore the Endpoints Reference to see all available operations
• Check out code examples for common use cases