API Key Types

Understand the two types of API keys in Topsort and when to use each one for different endpoints.

Topsort uses two types of API keys for different purposes.

Quick Reference

Key Type	Purpose
Marketplace API Key	Auction and event endpoints
Advanced API Key	Catalog sync, campaigns, reporting, billing

Most integrations need both key types: an Advanced key for catalog sync, campaigns, and reporting, and a Marketplace key for auctions and events.

Which Key Do I Need?

Endpoint	Key Type
POST /v2/auctions	Marketplace
POST /v2/events	Marketplace
/public/v1/catalog-search-service/*	Advanced
/public/v1/campaign-service/*	Advanced
/public/v1/reporting-service/*	Advanced
/public/v1/billing-service/*	Advanced

Common Errors

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

Causes:

• API key not included in Authorization header
• Key is malformed or expired
• Using Advanced key on Marketplace-only endpoint

Fix: Verify header format: Authorization: Bearer YOUR_API_KEY

403 Forbidden

{
  "error": "Forbidden", 
  "message": "Insufficient permissions"
}

Causes:

• Using an Advanced key on an endpoint that requires a Marketplace key
• Using a Marketplace key on an endpoint that requires an Advanced key

Fix: Use the key type that matches the endpoint — see Which Key Do I Need? above

How to Get Your Keys

Marketplace API Key

1. Access Topsort Admin

   Log in to your Topsort Admin dashboard

2. Navigate to API Settings

   Go to Settings → API Integration

3. Create API Key

   Click “Generate API key” and select “Marketplace API key”

4. Copy and Store

   Copy the key immediately and store it securely (it’s only shown once)

Advanced API Key

1. Access Topsort Admin

   Log in to your Topsort Admin dashboard

2. Navigate to API Settings

   Go to Settings → API Access

3. Generate Key

   Click “Generate Key” to create your Advanced API key

4. Copy and Store

   Copy the key and store it securely in your environment variables

Security Best Practices

• Never commit keys to version control
• Store keys in environment variables
• Rotate keys regularly
• Use different keys for different environments (dev, staging, production)
• Restrict key access to only necessary team members