Skip to main content
The eBay MCP Server supports two authentication methods, each designed for different use cases and offering different levels of API access and rate limits.

​
Authentication Methods

User Tokens

Recommended for productionFull API access with high rate limits (10,000-50,000 requests/day)

Client Credentials

Quick setup fallbackLimited API access with lower rate limits (1,000 requests/day)

​
Quick Comparison

FeatureUser TokensClient Credentials
Rate Limit10,000-50,000/day1,000/day
Setup ComplexityOAuth 2.0 flow requiredSimple - just ID and Secret
API AccessFull access to all 230+ toolsLimited to public/app-level operations
User-specific Data✅ Yes❌ No
Automatic Refresh✅ YesN/A (always valid)
Best ForProduction, seller operationsTesting, development
For most use cases, you’ll want user tokens. They provide full API access and significantly higher rate limits.

​
How Authentication Works

​
User Tokens (OAuth 2.0)

User tokens use the OAuth 2.0 authorization flow to grant your MCP server access to a seller’s eBay account.
1

User Authorization

The seller authorizes your application through eBay’s OAuth interface.
2

Token Exchange

Your application exchanges the authorization code for access and refresh tokens.
3

API Access

The MCP server uses the access token to make API calls on behalf of the user.
4

Automatic Refresh

When the access token expires (typically after 2 hours), the server automatically uses the refresh token to obtain a new access token.
The eBay MCP Server handles token refresh automatically - you don’t need to manage token expiration manually.

​
Client Credentials

Client credentials use a simpler application-level authentication that doesn’t require user authorization.
1

Configuration

You provide your eBay Client ID and Client Secret.
2

Automatic Authentication

The MCP server automatically obtains an application access token from eBay.
3

Limited API Access

The server can only access public and app-level endpoints.
Client credentials cannot access user-specific data like inventory, orders, or seller analytics.

​
Rate Limits Explained

Understanding rate limits is crucial for choosing the right authentication method.

​
User Token Limits

The daily rate limit for user tokens depends on your eBay seller account type:
Who qualifies:
  • New eBay sellers
  • Individual sellers
  • Low-volume accounts
What you can do:
  • Manage up to ~50 active listings
  • Process daily orders
  • Run basic marketing campaigns
  • View analytics regularly
Who qualifies:
  • Registered business accounts
  • Medium-volume sellers
  • eBay Store subscribers
What you can do:
  • Manage hundreds of active listings
  • Handle high order volumes
  • Run multiple marketing campaigns
  • Frequent analytics queries
Who qualifies:
  • Large-volume sellers
  • eBay partner accounts
  • High-tier eBay Store subscribers
What you can do:
  • Manage thousands of listings
  • Process hundreds of orders daily
  • Complex automation workflows
  • Real-time analytics and monitoring
Check your current rate limit in the eBay Developer Portal under your account settings.

​
Client Credentials Limits

Fixed at 1,000 requests/day regardless of account type.
This is sufficient for:
  • Testing and development
  • Occasional API exploration
  • Low-frequency automation
  • Learning the eBay APIs
Not recommended for:
  • Production seller operations
  • High-frequency automation
  • Managing active inventory
  • Processing orders

​
Choosing the Right Method

Use this decision tree to select the appropriate authentication method:
  • I'm Just Getting Started
  • I'm Building for Production
  • I'm Not Sure
Recommended: Client Credentials ✅Why:
  • Faster setup (no OAuth flow)
  • Perfect for learning and testing
  • Can upgrade to user tokens later
Next steps:
  1. Get your eBay Client ID and Secret
  2. Configure with environment variables
  3. Start exploring the APIs

Client Credentials Guide

Follow our step-by-step setup guide

​
Security Considerations

Both authentication methods require careful handling of credentials:

​
Protecting Your Credentials

Always use environment variables for credentials:
# ✅ Good: Use .env file (add to .gitignore)
EBAY_CLIENT_ID=your_client_id
EBAY_CLIENT_SECRET=your_client_secret

# ❌ Bad: Never hardcode in source code
const clientId = "YourAppId-12345"
The .env file should always be in .gitignore to prevent accidental commits.
Best practice:
  • Separate Sandbox credentials for testing
  • Separate Production credentials for live operations
  • Never mix Sandbox and Production
File organization:
.env.sandbox      # For development
.env.production   # For production
.env             # Active config (in .gitignore)
For production environments:
  • Rotate credentials every 90 days
  • Immediately rotate if compromised
  • Keep audit logs of rotation
How to rotate:
  1. Generate new credentials in eBay Developer Portal
  2. Update .env file
  3. If using user tokens, run npm run setup to regenerate tokens
  4. Delete old credentials from eBay portal
Regular security checks:
  • Review API usage in eBay Developer Portal
  • Monitor for unexpected API calls
  • Set up alerts for rate limit spikes
  • Check token refresh patterns
The eBay Developer Portal provides detailed usage analytics to help you detect anomalies.

​
Environment Variables

Both authentication methods use environment variables for configuration.

​
Required for Both Methods

# eBay application credentials
EBAY_CLIENT_ID=YourAppName-YourApp-SBX-1234abcd-567890ab
EBAY_CLIENT_SECRET=SBX-1234abcd-5678-90ab-cdef-1234

# API environment (sandbox or production)
EBAY_ENVIRONMENT=sandbox

# OAuth redirect URI (required for user tokens)
EBAY_REDIRECT_URI=http://localhost:3000/callback

​
Additional for User Tokens

# User access token (obtained via OAuth flow)
EBAY_USER_ACCESS_TOKEN=v^1.1#i^1#...

# User refresh token (for automatic renewal)
EBAY_USER_REFRESH_TOKEN=v^1.1#i^1#...

# Token expiry timestamp
EBAY_USER_TOKEN_EXPIRY=2024-12-31T23:59:59.000Z
User token variables are automatically populated when you run npm run setup or npm run auto-setup.

​
Authentication Flow in the MCP Server

Understanding how the MCP server handles authentication internally:

​
Startup Sequence

  1. Load Environment Variables
    • Read .env file
    • Validate required variables
  2. Check for User Tokens
    • If user tokens present and valid → use user token authentication
    • If user tokens missing or expired → fall back to client credentials
  3. Initialize Authentication
    • Obtain initial access token
    • Set up automatic refresh for user tokens
    • Register all available tools based on authentication type
  4. Validate Connection
    • Test API connectivity
    • Confirm authentication is working
    • Log authentication status
You can see the authentication status in the server logs when it starts.

​
During Operation

The MCP server handles authentication transparently:
  • Before each API call: Checks if access token is still valid
  • If token expired: Automatically refreshes using refresh token
  • If refresh fails: Falls back to client credentials if available
  • If all auth fails: Returns clear error message
You never need to manually manage tokens - the server does it all automatically!

​
Troubleshooting Authentication

​
Common Issues

Symptoms:
  • “Authentication failed” errors
  • Server won’t start
  • 401 Unauthorized responses
Solutions:
  1. Verify credentials in eBay Developer Portal
  2. Check for typos in .env file
  3. Ensure you’re using credentials from the correct environment (Sandbox vs Production)
  4. Remove any extra spaces or quotes around values
Symptoms:
  • Server falls back to client credentials
  • User-specific endpoints return errors
  • Token refresh fails
Solutions:
  1. Re-run npm run setup to regenerate tokens
  2. Verify redirect URI matches in eBay Developer Portal
  3. Check token expiry is in correct ISO 8601 format
  4. Ensure system clock is accurate
Symptoms:
  • HTTP 429 responses
  • “Rate limit exceeded” errors
  • API calls failing after many requests
Solutions:
  1. With client credentials: Upgrade to user tokens
  2. With user tokens: Wait for daily reset (UTC midnight)
  3. Long-term: Optimize your API usage patterns
  4. Consider: Upgrading your eBay seller account tier
Symptoms:
  • “Application not found” errors
  • Credentials work in portal but not in server
  • Inconsistent behavior
Solutions:
  1. Check EBAY_ENVIRONMENT in .env matches your credentials
  2. Sandbox credentials only work with EBAY_ENVIRONMENT=sandbox
  3. Production credentials only work with EBAY_ENVIRONMENT=production
  4. Never mix Sandbox and Production credentials

More Help

See the comprehensive troubleshooting guide

​
Next Steps

Ready to set up authentication? Follow the guide for your chosen method:

OAuth 2.0 Setup

Set up user tokens for full API access

Client Credentials

Quick setup with client credentials

Token Management

Learn about token refresh and lifecycle

Quickstart Guide

Complete setup guide with authentication

​
Learn More

eBay OAuth Documentation

Official eBay OAuth 2.0 documentation

Rate Limits Deep Dive

Understanding and optimizing rate limits

Security Best Practices

Comprehensive security guidelines

Configuration Guide

All configuration options explained