Client Credentials

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.

Time to complete: 2-3 minutesPrerequisites:

eBay Developer account
Client ID and Client Secret from eBay Developer Portal

What Are Client Credentials?

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

Quick Setup

No OAuth flow needed - just add credentials to .env

Automatic Authentication

Server obtains access tokens automatically

Lower Rate Limits

1,000 requests/day (vs 10,000-50,000 for user tokens)

Limited Access

Public/app-level operations only

When to Use Client Credentials

✅ Good For
❌ Not Recommended For
🔄 Upgrade Path

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

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

Switching from client credentials to user tokens requires no code changes - just update your .env file!

Quick Setup Guide

Step 1: Get Your Credentials

Visit eBay Developer Portal and sign in with your eBay account.

Navigate to Application Keys

Click My Account in the top right
Select Application Keys from the dropdown

Create or Select Application

Option A: Create new application

Click Create an Application Key
Choose Sandbox environment (for testing)
Fill in application details
Click Create

Option B: Use existing application

Select your existing application
Choose Sandbox or Production tab

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

Keep these credentials secure - they provide access to eBay APIs!

Step 2: Configure the MCP Server

Using Environment Variables
Using MCP Client Config
Using Docker

Recommended approach:Create or edit .env file in the project root:

# Copy example file
cp .env.example .env

Add your credentials:

# 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

That’s it! The server will automatically use client credentials mode since no user tokens are provided.

For Claude Desktop, Cursor, etc.:Add credentials directly to your MCP client configuration:

{
  "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"
      }
    }
  }
}

Use absolute paths for the server location.

For containerized deployments:Pass credentials as environment variables:

docker run \
  -e EBAY_CLIENT_ID=YourAppId \
  -e EBAY_CLIENT_SECRET=YourCertId \
  -e EBAY_ENVIRONMENT=sandbox \
  ebay-mcp-server

Or use a .env file:

docker run --env-file .env ebay-mcp-server

Step 3: Verify Setup

Validate Configuration

npm run validate-config

Expected output:

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

Start the Server

npm start

Check the logs for:

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

Your server is now running with client credentials!

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.

Some tools will return errors with client credentials - this is expected for user-specific operations.

How Client Credentials Work

Understanding the authentication flow:

Server Startup

When the MCP server starts:

Loads EBAY_CLIENT_ID and EBAY_CLIENT_SECRET from environment
Checks for user tokens (none found for client credentials mode)
Enters client credentials mode

Obtain Application Token

Server requests an application access token from eBay:

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

Receive Token

eBay responds with an application access token:

{
  "access_token": "v^1.1#i^1#p^3#...",
  "token_type": "Application Access Token",
  "expires_in": 7200
}

Use Token for API Calls

Server includes token in all API requests:

GET https://api.ebay.com/sell/inventory/v1/inventory_item
Authorization: Bearer v^1.1#i^1#p^3#...

Automatic Renewal

When the token expires (~2 hours):

Server automatically requests a new token
Uses refreshed token for subsequent calls
No manual intervention needed

Unlike user tokens, application tokens don’t have refresh tokens - the server just requests a new one when needed.

Available Operations

What Works with Client Credentials

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

These are informational endpoints that don’t require user authorization.

What Doesn’t Work

User-Specific Data

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.

Seller Operations

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.

Marketing & Promotions

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.

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

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

Managing Rate Limits

Monitor Usage
Optimize Usage
Upgrade When Needed

Track your API usage:

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

In Server Logs:

LOG_LEVEL=info
LOG_REQUESTS=true

Logs show each API call:

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

Via Rate Limit Headers: eBay includes rate limit info in responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 873
X-RateLimit-Reset: 1640995200

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:

npm run setup

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

Upgrading requires no code changes - just environment variable updates!

Troubleshooting

Authentication Fails on Startup

Error:

Error: Invalid client credentials

Possible causes:

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

Solutions:

Verify credentials in eBay Developer Portal
Check EBAY_ENVIRONMENT matches credential type

Remove quotes and extra spaces from .env values:

# ✅ Correct
EBAY_CLIENT_ID=YourAppId-12345

# ❌ Wrong
EBAY_CLIENT_ID="YourAppId-12345"
EBAY_CLIENT_ID= YourAppId-12345

API Calls Return 401 Unauthorized

Error:

Error: 401 Unauthorized - Invalid token

Possible causes:

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

Solutions:

Restart server to obtain fresh token
Verify credentials still valid in portal
Check if endpoint requires user authorization:
```
# Check server logs
[ERROR] Endpoint requires user-level access
```
→ Upgrade to user tokens if needed

Rate Limit Exceeded

Error:

Error: 429 Too Many Requests - Rate limit exceeded

Cause: You’ve made more than 1,000 requests today.Immediate solutions:

Wait until UTC midnight for reset
Upgrade to user tokens for higher limits:
```
npm run setup
```

Long-term solutions:

Implement request caching
Optimize API call patterns
Use batch operations
Consider user tokens for production

Some Tools Don't Work

Issue: Certain MCP tools return errors or “not available”Cause: Client credentials can’t access user-specific operationsAffected tool categories:

Inventory management
Order fulfillment
Marketing/promotions
Seller analytics

Solution: Upgrade to OAuth user tokens:

npm run setup

This enables all 230+ tools with full functionality.

Upgrading to User Tokens

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

Keep Existing Client Credentials

Your Client ID and Secret stay the same:

# These don't change
EBAY_CLIENT_ID=YourAppId-12345
EBAY_CLIENT_SECRET=YourCertId-67890
EBAY_ENVIRONMENT=sandbox
EBAY_REDIRECT_URI=http://localhost:3000/callback

Run OAuth Setup

npm run setup

This adds user tokens to your .env:

# 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

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

You’re now using user tokens with full API access!

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.

Security Best Practices

Protect Your Credentials

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

Compromised credentials give API access - protect them like passwords!

Separate Sandbox and Production

Use different credentials per environment:

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

Monitor Usage

Regularly check for anomalies:

In eBay Developer Portal:
- Review API usage analytics
- Check request patterns
- Monitor for unexpected spikes
Set up alerts:
- Email when approaching rate limits
- Notify on authentication failures
- Alert on unusual activity patterns
Log analysis:
```
LOG_LEVEL=info
LOG_REQUESTS=true
```
Review logs for suspicious patterns.

Rotate Credentials

Periodic credential rotation:For production:

Generate new credentials in portal
Update .env with new values
Test new credentials work
Delete old credentials from portal

Rotation schedule:

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

Keep audit logs of all credential rotations.

Next Steps

Upgrade to OAuth

Get user tokens for full API access

Understand Rate Limits

Learn about API rate limits and optimization

Explore Available Tools

See what’s possible with the MCP server

Best Practices

Optimize your MCP server usage

Comparison: Client Credentials vs User Tokens

Setup Complexity
API Access
Rate Limits
Use Cases

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

Additional Resources

eBay Client Credentials Guide

Official eBay client credentials documentation

Authentication Overview

Compare all authentication methods

Configuration Guide

Complete configuration reference

Troubleshooting

Solve common authentication issues

Getting Started

Authentication

Core Features

Guides

MCP Integration

Advanced

Support

What Are Client Credentials?

Quick Setup

Automatic Authentication

Lower Rate Limits

Limited Access

When to Use Client Credentials

Quick Setup Guide

Step 1: Get Your Credentials

Step 2: Configure the MCP Server

Step 3: Verify Setup

How Client Credentials Work

Available Operations

What Works with Client Credentials

What Doesn’t Work

Rate Limits

Daily Limit

Managing Rate Limits

Troubleshooting

Upgrading to User Tokens

Security Best Practices

Next Steps

Upgrade to OAuth

Understand Rate Limits

Explore Available Tools

Best Practices

Comparison: Client Credentials vs User Tokens

Additional Resources

eBay Client Credentials Guide

Authentication Overview

Configuration Guide

Troubleshooting

Getting Started

Authentication

Core Features

Guides

MCP Integration

Advanced

Support

​What Are Client Credentials?

Quick Setup

Automatic Authentication

Lower Rate Limits

Limited Access

​When to Use Client Credentials

​Quick Setup Guide

​Step 1: Get Your Credentials

​Step 2: Configure the MCP Server

​Step 3: Verify Setup

​How Client Credentials Work

​Available Operations

​What Works with Client Credentials

​What Doesn’t Work

​Rate Limits

​Daily Limit

​Managing Rate Limits

​Troubleshooting

​Upgrading to User Tokens

​Security Best Practices

​Next Steps

Upgrade to OAuth

Understand Rate Limits

Explore Available Tools

Best Practices

​Comparison: Client Credentials vs User Tokens

​Additional Resources

eBay Client Credentials Guide

Authentication Overview

Configuration Guide

Troubleshooting

What Are Client Credentials?

When to Use Client Credentials

Quick Setup Guide

Step 1: Get Your Credentials

Step 2: Configure the MCP Server

Step 3: Verify Setup

How Client Credentials Work

Available Operations

What Works with Client Credentials

What Doesn’t Work

Rate Limits

Daily Limit

Managing Rate Limits

Troubleshooting

Upgrading to User Tokens

Security Best Practices

Next Steps

Comparison: Client Credentials vs User Tokens

Additional Resources