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

# Client Credentials

> Quick setup with eBay client credentials authentication

Client credentials provide a simple way to authenticate the eBay MCP Server without the OAuth 2.0 flow. This method is perfect for getting started, testing, and development.

<Info>
  **Time to complete:** 2-3 minutes

  **Prerequisites:**

  * eBay Developer account
  * Client ID and Client Secret from eBay Developer Portal
</Info>

## What Are Client Credentials?

Client credentials (also called "application-level authentication") use only your eBay App ID and Cert ID to authenticate API requests.

<CardGroup cols={2}>
  <Card title="Quick Setup" icon="rocket">
    No OAuth flow needed - just add credentials to `.env`
  </Card>

  <Card title="Automatic Authentication" icon="magic-wand">
    Server obtains access tokens automatically
  </Card>

  <Card title="Lower Rate Limits" icon="gauge">
    1,000 requests/day (vs 10,000-50,000 for user tokens)
  </Card>

  <Card title="Limited Access" icon="lock">
    Public/app-level operations only
  </Card>
</CardGroup>

## When to Use Client Credentials

<Tabs>
  <Tab title="✅ Good For">
    **Client credentials are ideal for:**

    * **Getting started** - Quickest way to try the MCP server
    * **Development** - Test and learn the APIs
    * **Testing** - Validate your workflows
    * **Low-volume usage** - Occasional API exploration
    * **Public data** - Accessing non-user-specific information

    **Benefits:**

    * Setup in minutes
    * No browser authorization needed
    * Simple configuration
    * Perfect for learning
  </Tab>

  <Tab title="❌ Not Recommended For">
    **Avoid client credentials for:**

    * **Production seller operations** - Need user tokens
    * **High-frequency automation** - Rate limits too low
    * **User-specific data** - Inventory, orders, analytics
    * **Managing listings** - Requires user authorization
    * **Processing orders** - User-level access required

    **Limitations:**

    * Only 1,000 requests/day
    * Cannot access seller data
    * Limited to public endpoints
    * Cannot modify user resources
  </Tab>

  <Tab title="🔄 Upgrade Path">
    **Start with client credentials, then upgrade:**

    **Week 1: Learn**

    * Use client credentials to explore APIs
    * Test basic functionality
    * Learn tool capabilities

    **Week 2: Test**

    * Validate your workflows
    * Identify required APIs
    * Check rate limit needs

    **Week 3: Upgrade**

    * Set up OAuth user tokens
    * Test with full API access
    * Verify higher rate limits

    **Week 4: Deploy**

    * Move to production with user tokens
    * Full 230+ tools available
    * 10,000-50,000 requests/day

    <Tip>
      Switching from client credentials to user tokens requires no code changes - just update your `.env` file!
    </Tip>
  </Tab>
</Tabs>

## Quick Setup Guide

### Step 1: Get Your Credentials

<Steps>
  <Step title="Sign in to eBay Developer Portal">
    Visit [eBay Developer Portal](https://developer.ebay.com) and sign in with your eBay account.
  </Step>

  <Step title="Navigate to Application Keys">
    1. Click **My Account** in the top right
    2. Select **Application Keys** from the dropdown
  </Step>

  <Step title="Create or Select Application">
    **Option A: Create new application**

    1. Click **Create an Application Key**
    2. Choose **Sandbox** environment (for testing)
    3. Fill in application details
    4. Click **Create**

    **Option B: Use existing application**

    1. Select your existing application
    2. Choose **Sandbox** or **Production** tab
  </Step>

  <Step title="Copy Your Credentials">
    Note these values:

    **Sandbox:**

    * **App ID (Client ID):** `YourAppName-YourApp-SBX-1234abcd-567890ab`
    * **Cert ID (Client Secret):** `SBX-1234abcd-5678-90ab-cdef-1234`

    **Production:**

    * **App ID (Client ID):** `YourAppName-YourApp-PRD-1234abcd-567890ab`
    * **Cert ID (Client Secret):** `PRD-1234abcd-5678-90ab-cdef-1234`

    <Warning>
      Keep these credentials secure - they provide access to eBay APIs!
    </Warning>
  </Step>
</Steps>

### Step 2: Configure the MCP Server

<Tabs>
  <Tab title="Using Environment Variables">
    **Recommended approach:**

    Create or edit `.env` file in the project root:

    ```bash theme={null}
    # Copy example file
    cp .env.example .env
    ```

    Add your credentials:

    ```bash theme={null}
    # eBay API Credentials
    EBAY_CLIENT_ID=YourAppName-YourApp-SBX-1234abcd-567890ab
    EBAY_CLIENT_SECRET=SBX-1234abcd-5678-90ab-cdef-1234

    # Environment (sandbox or production)
    EBAY_ENVIRONMENT=sandbox

    # Redirect URI (required even for client credentials)
    EBAY_REDIRECT_URI=http://localhost:3000/callback
    ```

    <Info>
      That's it! The server will automatically use client credentials mode since no user tokens are provided.
    </Info>
  </Tab>

  <Tab title="Using MCP Client Config">
    **For Claude Desktop, Cursor, etc.:**

    Add credentials directly to your MCP client configuration:

    ```json theme={null}
    {
      "mcpServers": {
        "ebay": {
          "command": "node",
          "args": ["/path/to/ebay-mcp-server/build/index.js"],
          "env": {
            "EBAY_CLIENT_ID": "YourAppName-YourApp-SBX-1234abcd-567890ab",
            "EBAY_CLIENT_SECRET": "SBX-1234abcd-5678-90ab-cdef-1234",
            "EBAY_ENVIRONMENT": "sandbox"
          }
        }
      }
    }
    ```

    <Tip>
      Use absolute paths for the server location.
    </Tip>
  </Tab>

  <Tab title="Using Docker">
    **For containerized deployments:**

    Pass credentials as environment variables:

    ```bash theme={null}
    docker run \
      -e EBAY_CLIENT_ID=YourAppId \
      -e EBAY_CLIENT_SECRET=YourCertId \
      -e EBAY_ENVIRONMENT=sandbox \
      ebay-mcp-server
    ```

    Or use a `.env` file:

    ```bash theme={null}
    docker run --env-file .env ebay-mcp-server
    ```
  </Tab>
</Tabs>

### Step 3: Verify Setup

<Steps>
  <Step title="Validate Configuration">
    ```bash theme={null}
    npm run validate-config
    ```

    Expected output:

    ```
    ✅ Client ID: Valid
    ✅ Client Secret: Valid
    ✅ Environment: sandbox
    ✅ Authentication mode: Client Credentials
    ✅ Rate limit: 1,000 requests/day
    ```
  </Step>

  <Step title="Start the Server">
    ```bash theme={null}
    npm start
    ```

    Check the logs for:

    ```
    [INFO] Client credentials mode enabled
    [INFO] Rate limit: 1,000 requests/day
    [INFO] 230+ tools registered (limited access)
    ```

    <Check>
      Your server is now running with client credentials!
    </Check>
  </Step>

  <Step title="Test API Access">
    Try a simple API call through your MCP client:

    > "What eBay marketplaces are available?"

    This calls a public endpoint that works with client credentials.

    <Info>
      Some tools will return errors with client credentials - this is expected for user-specific operations.
    </Info>
  </Step>
</Steps>

## How Client Credentials Work

Understanding the authentication flow:

<Steps>
  <Step title="Server Startup">
    When the MCP server starts:

    1. Loads `EBAY_CLIENT_ID` and `EBAY_CLIENT_SECRET` from environment
    2. Checks for user tokens (none found for client credentials mode)
    3. Enters client credentials mode
  </Step>

  <Step title="Obtain Application Token">
    Server requests an application access token from eBay:

    ```http theme={null}
    POST https://api.ebay.com/identity/v1/oauth2/token
    Content-Type: application/x-www-form-urlencoded
    Authorization: Basic <base64(client_id:client_secret)>

    grant_type=client_credentials
    &scope=https://api.ebay.com/oauth/api_scope
    ```
  </Step>

  <Step title="Receive Token">
    eBay responds with an application access token:

    ```json theme={null}
    {
      "access_token": "v^1.1#i^1#p^3#...",
      "token_type": "Application Access Token",
      "expires_in": 7200
    }
    ```
  </Step>

  <Step title="Use Token for API Calls">
    Server includes token in all API requests:

    ```http theme={null}
    GET https://api.ebay.com/sell/inventory/v1/inventory_item
    Authorization: Bearer v^1.1#i^1#p^3#...
    ```
  </Step>

  <Step title="Automatic Renewal">
    When the token expires (\~2 hours):

    1. Server automatically requests a new token
    2. Uses refreshed token for subsequent calls
    3. No manual intervention needed
  </Step>
</Steps>

<Info>
  Unlike user tokens, application tokens don't have refresh tokens - the server just requests a new one when needed.
</Info>

## Available Operations

### What Works with Client Credentials

<Accordion title="Public Endpoints">
  **Available operations:**

  * Get marketplace information
  * View eBay policies (generic)
  * Access public metadata
  * Query eBay programs
  * Get location details

  **Example tools:**

  * `getEbayMarketplaces`
  * `getReturnPolicyTypes`
  * `getPaymentPolicyCategories`

  <Info>
    These are informational endpoints that don't require user authorization.
  </Info>
</Accordion>

### What Doesn't Work

<AccordionGroup>
  <Accordion title="User-Specific Data" icon="user">
    **Not available:**

    * User's inventory items
    * Seller's orders
    * Personal analytics
    * Account-specific settings

    **Error message:**

    ```
    Error: This endpoint requires user authorization
    ```

    **Solution:** Upgrade to user tokens via OAuth 2.0.
  </Accordion>

  <Accordion title="Seller Operations" icon="store">
    **Not available:**

    * Create/update listings
    * Manage offers
    * Process orders
    * Handle returns
    * Update inventory

    **Error message:**

    ```
    Error: Insufficient permissions for this operation
    ```

    **Solution:** Use user tokens for seller operations.
  </Accordion>

  <Accordion title="Marketing & Promotions" icon="megaphone">
    **Not available:**

    * Create campaigns
    * Manage promotions
    * View campaign analytics
    * Optimize promoted listings

    **Error message:**

    ```
    Error: Marketing operations require user-level access
    ```

    **Solution:** Set up OAuth user tokens.
  </Accordion>
</AccordionGroup>

## Rate Limits

### Daily Limit

**Fixed at 1,000 requests per day** for all client credentials, regardless of account type.

**What this means:**

* \~42 requests per hour
* \~0.7 requests per minute
* Resets daily at UTC midnight

<Warning>
  Once you hit 1,000 requests, all API calls will fail until the next day.
</Warning>

### Managing Rate Limits

<Tabs>
  <Tab title="Monitor Usage">
    **Track your API usage:**

    1. **In eBay Developer Portal:**
       * View **Application Keys** → **Analytics**
       * See real-time request counts
       * Monitor daily/monthly trends

    2. **In Server Logs:**

       ```bash theme={null}
       LOG_LEVEL=info
       LOG_REQUESTS=true
       ```

       Logs show each API call:

       ```
       [INFO] API call: getInventoryItems (remaining: 987/1000)
       ```

    3. **Via Rate Limit Headers:**
       eBay includes rate limit info in responses:
       ```
       X-RateLimit-Limit: 1000
       X-RateLimit-Remaining: 873
       X-RateLimit-Reset: 1640995200
       ```
  </Tab>

  <Tab title="Optimize Usage">
    **Strategies to stay under 1,000/day:**

    1. **Cache responses**
       * Store frequently accessed data
       * Reduce duplicate requests
       * Use conditional requests (ETags)

    2. **Batch operations**
       * Use bulk endpoints where available
       * Combine multiple queries
       * Schedule batch jobs

    3. **Smart polling**
       * Don't poll constantly
       * Use webhooks when possible
       * Increase polling intervals

    4. **Prioritize requests**
       * Focus on essential operations
       * Defer non-critical queries
       * Implement request queuing

    <Tip>
      Monitor your usage patterns to identify optimization opportunities.
    </Tip>
  </Tab>

  <Tab title="Upgrade When Needed">
    **Signs you need user tokens:**

    * Hitting 1,000/day limit regularly
    * Need access to user-specific data
    * Running seller operations
    * Automating inventory management
    * Processing orders

    **Upgrade process:**

    ```bash theme={null}
    npm run setup
    ```

    Complete OAuth flow to get user tokens with 10,000-50,000/day limits.

    <Info>
      Upgrading requires no code changes - just environment variable updates!
    </Info>
  </Tab>
</Tabs>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication Fails on Startup">
    **Error:**

    ```
    Error: Invalid client credentials
    ```

    **Possible causes:**

    1. Incorrect Client ID or Secret
    2. Wrong environment (Sandbox vs Production mismatch)
    3. Typos or extra spaces in `.env`

    **Solutions:**

    1. Verify credentials in [eBay Developer Portal](https://developer.ebay.com)
    2. Check `EBAY_ENVIRONMENT` matches credential type
    3. Remove quotes and extra spaces from `.env` values:
       ```bash theme={null}
       # ✅ Correct
       EBAY_CLIENT_ID=YourAppId-12345

       # ❌ Wrong
       EBAY_CLIENT_ID="YourAppId-12345"
       EBAY_CLIENT_ID= YourAppId-12345
       ```
  </Accordion>

  <Accordion title="API Calls Return 401 Unauthorized">
    **Error:**

    ```
    Error: 401 Unauthorized - Invalid token
    ```

    **Possible causes:**

    1. Application token expired and renewal failed
    2. Client credentials revoked
    3. Trying to access user-specific endpoint

    **Solutions:**

    1. Restart server to obtain fresh token
    2. Verify credentials still valid in portal
    3. Check if endpoint requires user authorization:
       ```bash theme={null}
       # Check server logs
       [ERROR] Endpoint requires user-level access
       ```
       → Upgrade to user tokens if needed
  </Accordion>

  <Accordion title="Rate Limit Exceeded">
    **Error:**

    ```
    Error: 429 Too Many Requests - Rate limit exceeded
    ```

    **Cause:** You've made more than 1,000 requests today.

    **Immediate solutions:**

    1. Wait until UTC midnight for reset
    2. Upgrade to user tokens for higher limits:
       ```bash theme={null}
       npm run setup
       ```

    **Long-term solutions:**

    1. Implement request caching
    2. Optimize API call patterns
    3. Use batch operations
    4. Consider user tokens for production
  </Accordion>

  <Accordion title="Some Tools Don't Work">
    **Issue:** Certain MCP tools return errors or "not available"

    **Cause:** Client credentials can't access user-specific operations

    **Affected tool categories:**

    * Inventory management
    * Order fulfillment
    * Marketing/promotions
    * Seller analytics

    **Solution:** Upgrade to OAuth user tokens:

    ```bash theme={null}
    npm run setup
    ```

    This enables all 230+ tools with full functionality.
  </Accordion>
</AccordionGroup>

## Upgrading to User Tokens

Ready for full API access? Here's how to upgrade:

<Steps>
  <Step title="Keep Existing Client Credentials">
    Your Client ID and Secret stay the same:

    ```bash theme={null}
    # These don't change
    EBAY_CLIENT_ID=YourAppId-12345
    EBAY_CLIENT_SECRET=YourCertId-67890
    EBAY_ENVIRONMENT=sandbox
    EBAY_REDIRECT_URI=http://localhost:3000/callback
    ```
  </Step>

  <Step title="Run OAuth Setup">
    ```bash theme={null}
    npm run setup
    ```

    This adds user tokens to your `.env`:

    ```bash theme={null}
    # New tokens added automatically
    EBAY_USER_ACCESS_TOKEN=v^1.1#i^1#...
    EBAY_USER_REFRESH_TOKEN=v^1.1#i^1#...
    EBAY_USER_TOKEN_EXPIRY=2024-12-31T14:30:45.000Z
    ```
  </Step>

  <Step title="Server Automatically Switches">
    On next startup, the server detects user tokens and switches to OAuth mode:

    ```
    [INFO] User tokens detected
    [INFO] Authentication: OAuth 2.0 (User Tokens)
    [INFO] Rate limit: 10,000-50,000 requests/day
    [INFO] All 230+ tools enabled
    ```

    <Check>
      You're now using user tokens with full API access!
    </Check>
  </Step>

  <Step title="Fallback to Client Credentials">
    If user tokens fail or expire, server automatically falls back:

    ```
    [WARN] User token refresh failed, falling back to client credentials
    [INFO] Authentication: Client Credentials
    [INFO] Rate limit: 1,000 requests/day
    ```

    This ensures the server keeps working even if OAuth tokens have issues.
  </Step>
</Steps>

## Security Best Practices

<AccordionGroup>
  <Accordion title="Protect Your Credentials" icon="shield">
    **Client ID and Secret are sensitive:**

    ✅ **Do:**

    * Store in `.env` file
    * Add `.env` to `.gitignore`
    * Use environment variables in production
    * Set file permissions: `chmod 600 .env`

    ❌ **Don't:**

    * Commit to version control
    * Share publicly or in screenshots
    * Hardcode in source files
    * Send via email or chat

    <Warning>
      Compromised credentials give API access - protect them like passwords!
    </Warning>
  </Accordion>

  <Accordion title="Separate Sandbox and Production" icon="layer-group">
    **Use different credentials per environment:**

    ```bash theme={null}
    # .env.sandbox
    EBAY_CLIENT_ID=YourApp-SBX-12345
    EBAY_CLIENT_SECRET=SBX-67890
    EBAY_ENVIRONMENT=sandbox

    # .env.production
    EBAY_CLIENT_ID=YourApp-PRD-12345
    EBAY_CLIENT_SECRET=PRD-67890
    EBAY_ENVIRONMENT=production
    ```

    **Benefits:**

    * Isolate testing from production
    * Easier credential rotation
    * Better security boundaries
  </Accordion>

  <Accordion title="Monitor Usage" icon="eye">
    **Regularly check for anomalies:**

    1. **In eBay Developer Portal:**
       * Review API usage analytics
       * Check request patterns
       * Monitor for unexpected spikes

    2. **Set up alerts:**
       * Email when approaching rate limits
       * Notify on authentication failures
       * Alert on unusual activity patterns

    3. **Log analysis:**

       ```bash theme={null}
       LOG_LEVEL=info
       LOG_REQUESTS=true
       ```

       Review logs for suspicious patterns.
  </Accordion>

  <Accordion title="Rotate Credentials" icon="rotate">
    **Periodic credential rotation:**

    **For production:**

    1. Generate new credentials in portal
    2. Update `.env` with new values
    3. Test new credentials work
    4. Delete old credentials from portal

    **Rotation schedule:**

    * Every 90 days minimum
    * Immediately if compromised
    * Before/after team member changes

    <Info>
      Keep audit logs of all credential rotations.
    </Info>
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Upgrade to OAuth" icon="arrow-up" href="/authentication/oauth-setup">
    Get user tokens for full API access
  </Card>

  <Card title="Understand Rate Limits" icon="gauge" href="/advanced/rate-limits">
    Learn about API rate limits and optimization
  </Card>

  <Card title="Explore Available Tools" icon="tools" href="/api-reference/introduction">
    See what's possible with the MCP server
  </Card>

  <Card title="Best Practices" icon="lightbulb" href="/guides/best-practices">
    Optimize your MCP server usage
  </Card>
</CardGroup>

## Comparison: Client Credentials vs User Tokens

<Tabs>
  <Tab title="Setup Complexity">
    **Client Credentials:**

    * ✅ 2-3 minutes setup
    * ✅ No browser authorization
    * ✅ Just add ID and Secret
    * ✅ Works immediately

    **User Tokens:**

    * ⚠️ 10-15 minutes setup
    * ⚠️ OAuth flow required
    * ⚠️ Browser authorization needed
    * ⚠️ Additional configuration
  </Tab>

  <Tab title="API Access">
    **Client Credentials:**

    * ❌ Public endpoints only
    * ❌ No user-specific data
    * ❌ Cannot modify resources
    * ❌ Limited tool availability

    **User Tokens:**

    * ✅ All 230+ tools available
    * ✅ Full user data access
    * ✅ Create/update/delete operations
    * ✅ Complete API coverage
  </Tab>

  <Tab title="Rate Limits">
    **Client Credentials:**

    * ❌ 1,000 requests/day
    * ❌ Fixed limit
    * ❌ No upgrade options

    **User Tokens:**

    * ✅ 10,000-50,000/day
    * ✅ Based on account tier
    * ✅ Scalable with seller level
  </Tab>

  <Tab title="Use Cases">
    **Client Credentials:**

    * ✅ Learning and testing
    * ✅ Development
    * ✅ Low-volume operations
    * ✅ Public data queries

    **User Tokens:**

    * ✅ Production operations
    * ✅ Seller automation
    * ✅ Inventory management
    * ✅ Order processing
    * ✅ Marketing campaigns
  </Tab>
</Tabs>

## Additional Resources

<CardGroup cols={2}>
  <Card title="eBay Client Credentials Guide" icon="book" href="https://developer.ebay.com/api-docs/static/oauth-client-credentials-grant.html">
    Official eBay client credentials documentation
  </Card>

  <Card title="Authentication Overview" icon="shield" href="/authentication/overview">
    Compare all authentication methods
  </Card>

  <Card title="Configuration Guide" icon="gear" href="/configuration">
    Complete configuration reference
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/support/troubleshooting">
    Solve common authentication issues
  </Card>
</CardGroup>