Authentication

The SellerCockpit API uses API keys for authentication. Each API key has specific scopes that determine which resources it can access and what operations it can perform.

Creating API Keys

API keys are created through the SellerCockpit web application:

1. Navigate to Settings → API Keys
2. Click Create API Key
3. Provide a name and optional description
4. Select the appropriate scopes for your use case
5. Choose key type (Personal or Shared)
6. Optionally set an expiration date
7. Click Create

Important: The full API key is shown only once during creation. Store it securely - you won’t be able to retrieve it again.

API Key Format

API keys follow this format:

sellercockpit_live_abcdefghijklmnopqrstuvwxyz012345

• Prefix: sellercockpit_ (identifies the service)
• Environment: live_ or test_ (production vs sandbox)
• Random Part: 32 alphanumeric characters (unique identifier)

Only the first 24 characters are stored in the UI for identification purposes. The full key is hashed using SHA-256 and stored securely.

Authentication Header

Include your API key in every request using the Authorization header with the Bearer scheme:

Authorization: Bearer sellercockpit_live_abcdefghijklmnopqrstuvwxyz012345

Example Requests

Using cURL:

curl https://your-project.supabase.co/functions/v1/api-v1-contacts \
  -H "Authorization: Bearer sellercockpit_live_abcdefghijklmnopqrstuvwxyz012345" \
  -H "Content-Type: application/json"

Using JavaScript (fetch):

const response = await fetch(
  'https://your-project.supabase.co/functions/v1/api-v1-contacts',
  {
    headers: {
      'Authorization': 'Bearer sellercockpit_live_abcdefghijklmnopqrstuvwxyz012345',
      'Content-Type': 'application/json'
    }
  }
);

const data = await response.json();

Using Python (requests):

import requests

headers = {
    'Authorization': 'Bearer sellercockpit_live_abcdefghijklmnopqrstuvwxyz012345',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://your-project.supabase.co/functions/v1/api-v1-contacts',
    headers=headers
)

data = response.json()

API Key Scopes

Scopes control what operations an API key can perform. Use the principle of least privilege - only grant the scopes necessary for your integration.

Available Scopes

Scope	Description
read:all	Read access to all resources
write:all	Write access to all resources (create, update, delete)
read:organizations	Read organization data only
write:organizations	Create, update, delete organizations
read:contacts	Read contact data only
write:contacts	Create, update, delete contacts
read:deals	Read deal data only
write:deals	Create, update, delete deals
read:activities	Read activity logs only
write:activities	Create activities (calls, emails, meetings, notes)
read:tasks	Read task data only
write:tasks	Create, update, delete tasks
admin:all	Full administrative access (use with caution)

Scope Hierarchy

Some scopes provide hierarchical access:

• admin:all - Grants all permissions (equivalent to all scopes combined)
• read:all - Grants read access to all resources
• write:all - Grants write access to all resources

Example: If a key has read:all, it can access read:contacts, read:deals, etc. without needing each individual scope.

Recommended Scope Combinations

Read-only integration (analytics, reporting):

["read:all"]

Full integration (sync, automation):

["read:all", "write:all"]

Contact sync only:

["read:contacts", "write:contacts", "read:organizations"]

Deal pipeline automation:

["read:deals", "write:deals", "read:contacts"]

Activity logging only:

["write:activities"]

Key Types

Personal Keys

• Associated with a specific user
• Ideal for individual automation scripts or personal projects
• Automatically revoked when user leaves the company

Shared Keys

• Shared across the team
• Ideal for company-wide integrations (e.g., Zapier, n8n)
• Persist independently of individual user accounts

API Key Lifecycle

Active Keys

• Keys are active immediately after creation
• Can be temporarily disabled by setting is_active to false
• No requests are processed for inactive keys

Expiration

• Keys can have an optional expiration date
• Expired keys return API_KEY_EXPIRED error (401)
• Set expiration for temporary integrations or testing

Revocation

• Keys can be permanently revoked at any time
• Revoked keys cannot be reactivated
• Create a new key if you need access again

Security Best Practices

Storage

• Never commit API keys to version control (Git, SVN, etc.)
• Store keys in environment variables or secure key management systems
• Use .env files with .gitignore for local development
• Use platform-specific secret storage for production (AWS Secrets Manager, HashiCorp Vault, etc.)

Usage

• Use HTTPS only - Never send API keys over unencrypted HTTP
• Rotate keys regularly - Replace keys every 90 days for production systems
• Use specific scopes - Don’t use admin:all unless absolutely necessary
• Monitor usage - Check the API key dashboard for unexpected activity
• Revoke immediately - If a key is compromised, revoke it immediately

Environment Variables Example

.env file (never commit this):

SELLERCOCKPIT_API_KEY=sellercockpit_live_abcdefghijklmnopqrstuvwxyz012345
SELLERCOCKPIT_BASE_URL=https://your-project.supabase.co/functions/v1

Node.js usage:

require('dotenv').config();

const apiKey = process.env.SELLERCOCKPIT_API_KEY;
const baseUrl = process.env.SELLERCOCKPIT_BASE_URL;

Python usage:

import os
from dotenv import load_dotenv

load_dotenv()

api_key = os.getenv('SELLERCOCKPIT_API_KEY')
base_url = os.getenv('SELLERCOCKPIT_BASE_URL')

Error Responses

Missing API Key

curl https://your-project.supabase.co/functions/v1/api-v1-contacts

Response (401):

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing API key. Include it in the Authorization header as \"Bearer <your_api_key>\""
  }
}

Invalid API Key

curl https://your-project.supabase.co/functions/v1/api-v1-contacts \
  -H "Authorization: Bearer invalid_key_format"

Response (401):

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key format"
  }
}

Insufficient Permissions

# Trying to create a contact with a read-only API key
curl -X POST https://your-project.supabase.co/functions/v1/api-v1-contacts \
  -H "Authorization: Bearer sellercockpit_live_readonly123..." \
  -H "Content-Type: application/json" \
  -d '{"name": "John Doe"}'

Response (403):

{
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "This action requires the \"write:contacts\" scope"
  }
}

Revoked or Expired Key

Response (401):

{
  "error": {
    "code": "API_KEY_REVOKED",
    "message": "This API key has been revoked"
  }
}

or

{
  "error": {
    "code": "API_KEY_EXPIRED",
    "message": "This API key has expired"
  }
}

Monitoring API Key Usage

Track API key usage in the SellerCockpit web application:

• Last used: Timestamp of the most recent request
• Last IP: IP address of the most recent request
• Request count: Total number of requests made with this key
• Usage stats: Requests per day, week, and month

This helps identify:

• Unused keys that should be revoked
• Unexpected usage patterns that may indicate compromise
• Performance bottlenecks in your integrations

Next Steps

• Understand rate limits
• Learn about pagination
• Browse available endpoints