> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topsort.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Key Types

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

export const LastUpdated = ({date, lang = "en"}) => {
  const translations = {
    en: "Last updated:",
    es: "Última actualización:",
    pt: "Última atualização:",
    fr: "Dernière mise à jour:",
    de: "Zuletzt aktualisiert:"
  };
  const label = translations[lang] || translations.en;
  return <>
<style>{`
.last-updated-component {
display: inline-flex;
align-items: center;
gap: 8px;
padding: 10px 16px;
border-radius: 8px;
margin-top: 12px;
margin-bottom: 16px;
font-size: 14px;
background-color: rgba(0, 0, 0, 0.05);
border: 1px solid rgba(0, 0, 0, 0.12);
color: rgba(0, 0, 0, 0.75);
line-height: 1;
}

        .last-updated-component svg {
          flex-shrink: 0;
          vertical-align: middle;
        }

        .last-updated-component span {
          display: inline-flex !important;
          align-items: center !important;
          line-height: 1 !important;
        }

        [data-theme="dark"] .last-updated-component {
          background-color: #3a3a3a;
          border: 2px solid #888888;
          color: #ffffff;
        }

        [data-theme="dark"] .last-updated-component svg {
          stroke: #ffffff;
        }
      `}</style>
      <div className="last-updated-component">
        <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
          <circle cx="12" cy="12" r="10" />
          <polyline points="12 6 12 12 16 14" />
        </svg>
        <span>
          <strong style={{
    fontWeight: 600
  }}>{label}</strong> 
          <time dateTime={date}>{date}</time>
        </span>
      </div>
    </>;
};

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 |

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

## 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

```json theme={null}
{
  "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

```json theme={null}
{
  "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?](#which-key-do-i-need) above

## How to Get Your Keys

### Marketplace API Key

<Steps>
  <Step title="Access Topsort Admin">
    Log in to your Topsort Admin dashboard
  </Step>

  <Step title="Navigate to API Settings">
    Go to **Settings** → **API Integration**
  </Step>

  <Step title="Create API Key">
    Click **"Generate API key"** and select **"Marketplace API key"**
  </Step>

  <Step title="Copy and Store">
    Copy the key immediately and store it securely (it's only shown once)
  </Step>
</Steps>

### Advanced API Key

<Steps>
  <Step title="Access Topsort Admin">
    Log in to your Topsort Admin dashboard
  </Step>

  <Step title="Navigate to API Settings">
    Go to **Settings** → **API Access**
  </Step>

  <Step title="Generate Key">
    Click **"Generate Key"** to create your Advanced API key
  </Step>

  <Step title="Copy and Store">
    Copy the key and store it securely in your environment variables
  </Step>
</Steps>

## 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**

<LastUpdated date="2026-06-12" />