Skip to main content
The eBay MCP Server automatically manages OAuth tokens for you, but understanding how token management works helps you troubleshoot issues and optimize your setup.
Good news: The MCP server handles all token management automatically. This guide is for understanding what happens behind the scenes.

​
Token Types

The eBay MCP Server works with two types of OAuth tokens:

Access Token

Lifetime: ~2 hoursPurpose: Used for API requestsRefreshed: Automatically when expired

Refresh Token

Lifetime: 18 monthsPurpose: Obtain new access tokensRenewed: Each time it’s used

​
How Token Management Works

​
Automatic Token Lifecycle

1

Initial Authorization

When you complete OAuth setup, eBay provides:
  • Access token (valid ~2 hours)
  • Refresh token (valid 18 months)
  • Token expiry timestamp
These are saved to your .env file automatically.
2

Token Storage

The MCP server loads tokens from environment variables:
EBAY_USER_ACCESS_TOKEN=v^1.1#i^1#r^1#...
EBAY_USER_REFRESH_TOKEN=v^1.1#i^1#r^1#...
EBAY_USER_TOKEN_EXPIRY=2024-12-31T23:59:59.000Z
3

Token Validation

Before each API call, the server checks:
  • Is the access token still valid?
  • Has it expired based on the expiry timestamp?
4

Automatic Refresh

When the access token expires:
  1. Server uses refresh token to request new access token
  2. eBay returns new access token + new refresh token
  3. Server updates .env file with new tokens
  4. API call proceeds with new access token
5

Continuous Operation

This cycle repeats automatically:
  • Every ~2 hours, tokens refresh
  • Each refresh renews the refresh token
  • As long as the server runs occasionally, tokens never truly expire
You never need to manually refresh tokens - the MCP server does it all for you!

​
Token Expiry Details

​
Access Token Expiration

Typical lifetime: 7,200 seconds (2 hours) Expiry behavior:
  • Server checks expiry before each API call
  • Automatically refreshes if expired
  • Uses cached token if still valid (performance optimization)
Format in .env: 
EBAY_USER_TOKEN_EXPIRY=2024-12-31T14:30:45.000Z
The expiry timestamp is in ISO 8601 format with UTC timezone (the Z suffix).

​
Refresh Token Expiration

Typical lifetime: 540 days (18 months) Important: Each time you use a refresh token to get a new access token, eBay also provides a new refresh token with a fresh 18-month expiry. This means:
  • If you use the MCP server at least once every 18 months, your refresh token effectively never expires
  • Long periods of inactivity (>18 months) require re-authorization
  • Regular Use
  • Inactive Account
Scenario: You use the MCP server weeklyWhat happens:
  • Access tokens refresh every ~2 hours when needed
  • Each refresh renews the refresh token
  • Refresh token expiry resets to 18 months from last use
  • Result: Tokens never expire ✅

​
Token Refresh Process

​
When Refresh Happens

The server refreshes tokens in these situations:
  1. Before API calls - If access token is expired
  2. On server startup - If access token is expired
  3. Proactively - If token expires within next 5 minutes (configurable)

​
How Refresh Works

1

Detect Expiration

Server compares current time with EBAY_USER_TOKEN_EXPIRY:
if (currentTime >= tokenExpiry) {
  // Token expired, need to refresh
}
2

Call eBay Token Endpoint

Server makes a POST request to eBay’s token endpoint:
POST https://api.ebay.com/identity/v1/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=v^1.1#i^1#r^1#...
With Authorization header containing Client ID and Secret.
3

Receive New Tokens

eBay responds with:
{
  "access_token": "v^1.1#i^1#p^1#...",
  "token_type": "User Access Token",
  "expires_in": 7200,
  "refresh_token": "v^1.1#i^1#r^1#..."
}
4

Update Environment

Server updates .env file with new values:
EBAY_USER_ACCESS_TOKEN=<new_access_token>
EBAY_USER_REFRESH_TOKEN=<new_refresh_token>
EBAY_USER_TOKEN_EXPIRY=<calculated_expiry>
Expiry is calculated as: currentTime + expires_in seconds.
5

Continue Operation

The API call proceeds with the new access token.
All of this happens transparently - you won’t even notice tokens are being refreshed!

​
Monitoring Token Status

​
Check Current Token Status

View your current token information: 
cat .env | grep EBAY_USER
This shows:
  • Current access token
  • Current refresh token
  • When access token expires

​
Validate Tokens

Ensure your tokens are valid: 
npm run validate-config
This checks:
  • ✅ Tokens exist
  • ✅ Format is correct
  • ✅ Tokens work with eBay API
  • ✅ Expiry timestamp is valid
Run this after setup or if you suspect token issues.

​
Server Logs

The MCP server logs token-related events: 
[INFO] User tokens loaded successfully
[INFO] Access token expires at: 2024-12-31T14:30:45.000Z
[INFO] Access token refreshed successfully
[WARN] Access token expired, refreshing...
[ERROR] Token refresh failed: invalid_grant
Set LOG_LEVEL=debug in .env to see detailed token management logs.

​
Manual Token Operations

While automatic management is recommended, you can manually manage tokens if needed:

​
Manually Refresh Tokens

Force a token refresh: 
npm run refresh-tokens
This:
  1. Uses current refresh token
  2. Obtains new access and refresh tokens
  3. Updates .env file
Only use manual refresh for troubleshooting - the server handles this automatically.

​
Regenerate Tokens

If tokens are corrupted or invalid, regenerate them: 
npm run setup
This starts the OAuth flow from scratch:
  1. Opens browser for authorization
  2. Exchanges code for new tokens
  3. Saves to .env
This is the same process as initial OAuth setup.

​
Revoke Tokens

To revoke all tokens and start fresh:
1

Remove from .env

Delete or comment out token variables:
# EBAY_USER_ACCESS_TOKEN=...
# EBAY_USER_REFRESH_TOKEN=...
# EBAY_USER_TOKEN_EXPIRY=...
2

Revoke in eBay Portal (Optional)

  1. Sign in to eBay Developer Portal
  2. Navigate to User Tokens
  3. Find your application
  4. Click Revoke to invalidate tokens
3

Re-authorize

Run setup to get new tokens:
npm run setup

​
Token Security

​
Protecting Your Tokens

Tokens are credentials - protect them like passwords:✅ Do:
  • Store in .env file (add to .gitignore)
  • Use environment variables in production
  • Set file permissions: chmod 600 .env
  • Use secret management in cloud deployments
❌ Don’t:
  • Commit to version control
  • Share via email/chat
  • Include in screenshots
  • Log to console in production
  • Hardcode in source files
Regular security checks:
  • Review API usage in eBay Developer Portal
  • Check for unexpected token refreshes
  • Monitor for unusual activity patterns
  • Set up alerts for rate limit spikes
The eBay Developer Portal shows detailed API usage by token.
Best practices for production:
  • Re-authorize every 6-12 months
  • Immediately revoke if compromised
  • Test new tokens before switching
  • Keep audit logs of rotations
How to rotate:
  1. Run npm run setup to get new tokens
  2. Verify new tokens work
  3. (Optional) Revoke old tokens in eBay portal
  4. Update production deployment
If you suspect tokens are compromised:
  1. Immediately revoke in eBay Developer Portal
  2. Remove from .env and any backups
  3. Review recent API activity for unauthorized use
  4. Generate new tokens via npm run setup
  5. Update all deployments with new tokens
  6. Document the incident and response
Act quickly - compromised tokens give full API access!

​
Troubleshooting Token Issues

​
Common Problems

Symptoms:
  • “Token refresh failed” errors in logs
  • Server falls back to client credentials
  • 401 Unauthorized responses
Possible causes:
  1. Refresh token expired (>18 months inactive)
  2. Refresh token invalid or corrupted
  3. Client ID/Secret changed
  4. Network connectivity issues
Solutions:
  1. Re-run OAuth setup: 
    npm run setup
  2. Verify Client ID and Secret haven’t changed
  3. Check network connectivity to eBay APIs
  4. Review server logs for specific error messages
Symptoms:
  • Token expiry is always in the past
  • Constant refresh attempts
  • Performance degradation
Possible causes:
  1. System clock is incorrect
  2. Timezone mismatch
  3. .env file not being updated
Solutions:
  1. Check system time: date
  2. Ensure system clock is accurate
  3. Verify .env file permissions (must be writable)
  4. Check disk space (file updates might fail)
Symptoms:
  • Tokens refresh but .env still has old values
  • Manual edits to .env get reverted
  • Token expiry timestamp doesn’t update
Possible causes:
  1. File permissions issue
  2. Multiple instances running
  3. .env file locked by another process
Solutions:
  1. Check file permissions: 
    ls -la .env
chmod 644 .env
  2. Ensure only one instance is running
  3. Restart the MCP server
  4. Check for file system errors
Symptoms:
  • Server starts with user tokens but switches to client credentials
  • Limited API access after running
  • Higher rate limit errors
Possible causes:
  1. User tokens became invalid
  2. Token refresh failed
  3. Access token expired and refresh token missing
Solutions:
  1. Check server logs for token errors
  2. Verify all token variables in .env: 
    EBAY_USER_ACCESS_TOKEN
EBAY_USER_REFRESH_TOKEN
EBAY_USER_TOKEN_EXPIRY
  3. Re-run OAuth setup if tokens are missing
  4. Ensure refresh token is valid
Symptoms:
  • “Invalid token format” errors
  • Token validation fails
  • API calls return 401
Possible causes:
  1. Token string got truncated
  2. Extra spaces or newlines in .env
  3. Token got corrupted during copy/paste
Solutions:
  1. Re-run OAuth setup to get fresh tokens: 
    npm run setup
  2. Check .env for formatting issues
  3. Ensure no quotes around token values
  4. Verify no line breaks in token strings

​
Token Management Best Practices

​
For Development

  • Local Development
  • Team Development
Recommended setup:
  1. Use Sandbox environment
  2. Store tokens in .env file
  3. Add .env to .gitignore
  4. Use interactive setup wizard
  5. Let automatic refresh handle tokens
Sample .env:
EBAY_ENVIRONMENT=sandbox
EBAY_CLIENT_ID=YourSandboxAppId
EBAY_CLIENT_SECRET=YourSandboxCertId
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

​
For Production

  • Cloud Deployment
  • Monitoring
  • Disaster Recovery
Use environment variables, not .env files:AWS:
  • AWS Secrets Manager
  • Systems Manager Parameter Store
  • Environment variables in ECS/Lambda
Azure:
  • Azure Key Vault
  • App Service Configuration
Google Cloud:
  • Secret Manager
  • Cloud Run environment variables
Docker:
docker run -e EBAY_USER_ACCESS_TOKEN=... \
           -e EBAY_USER_REFRESH_TOKEN=... \
           ebay-mcp-server

​
Advanced Token Management

​
Token Caching

The MCP server caches access tokens in memory for performance: Benefits:
  • Reduces file I/O
  • Faster API calls
  • Less disk wear
Behavior:
  • Access token cached on first load
  • Cache invalidated on expiry
  • New token cached after refresh
Restart the server to clear the token cache.

​
Preemptive Refresh

The server can refresh tokens before they expire: Configuration: 
# Refresh token when <5 minutes remaining (default)
TOKEN_REFRESH_BUFFER=300
Benefits:
  • Prevents mid-request expiry
  • Smoother operation
  • Reduced API call failures

​
Multiple Environments

Managing tokens across environments: Structure: 
.env.sandbox        # Sandbox tokens
.env.production     # Production tokens
.env               # Current environment
Switching environments: 
# Switch to sandbox
cp .env.sandbox .env

# Switch to production
cp .env.production .env
Never mix Sandbox and Production tokens in the same .env file!

​
Next Steps

OAuth Setup

Learn how to set up OAuth tokens

Client Credentials

Understand the fallback authentication method

Rate Limits

Optimize your API usage

Troubleshooting

Solve common token issues

​
Additional Resources

eBay Token Documentation

Official eBay token management guide

Security Best Practices

Comprehensive security guidelines

Configuration Guide

All environment variables explained

Error Handling

Handle authentication errors gracefully