Token Management - eBay MCP Server

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

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.

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

Token Validation

Before each API call, the server checks:

Is the access token still valid?
Has it expired based on the expiry timestamp?

Automatic Refresh

When the access token expires:

Server uses refresh token to request new access token
eBay returns new access token + new refresh token
Server updates .env file with new tokens
API call proceeds with new access token

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:

Before API calls - If access token is expired
On server startup - If access token is expired
Proactively - If token expires within next 5 minutes (configurable)

How Refresh Works

Detect Expiration

Server compares current time with EBAY_USER_TOKEN_EXPIRY:

if (currentTime >= tokenExpiry) {
  // Token expired, need to refresh
}

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.

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

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.

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:

Uses current refresh token
Obtains new access and refresh tokens
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:

Opens browser for authorization
Exchanges code for new tokens
Saves to .env

This is the same process as initial OAuth setup.

Revoke Tokens

To revoke all tokens and start fresh:

Remove from .env

Delete or comment out token variables:

# EBAY_USER_ACCESS_TOKEN=...
# EBAY_USER_REFRESH_TOKEN=...
# EBAY_USER_TOKEN_EXPIRY=...

Revoke in eBay Portal (Optional)

Sign in to eBay Developer Portal
Navigate to User Tokens
Find your application
Click Revoke to invalidate tokens

Re-authorize

Run setup to get new tokens:

npm run setup

Token Security

Protecting Your Tokens

Never Expose 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

Monitor Token Usage

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.

Rotate Tokens Periodically

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:

Run npm run setup to get new tokens
Verify new tokens work
(Optional) Revoke old tokens in eBay portal
Update production deployment

Handle Token Compromise

If you suspect tokens are compromised:

Immediately revoke in eBay Developer Portal
Remove from .env and any backups
Review recent API activity for unauthorized use
Generate new tokens via npm run setup
Update all deployments with new tokens
Document the incident and response

Act quickly - compromised tokens give full API access!

Troubleshooting Token Issues

Common Problems

Token Refresh Fails

Symptoms:

“Token refresh failed” errors in logs
Server falls back to client credentials
401 Unauthorized responses

Possible causes:

Refresh token expired (>18 months inactive)
Refresh token invalid or corrupted
Client ID/Secret changed
Network connectivity issues

Solutions:

Re-run OAuth setup:
```
npm run setup
```
Verify Client ID and Secret haven’t changed
Check network connectivity to eBay APIs
Review server logs for specific error messages

Token Expiry Keeps Resetting

Symptoms:

Token expiry is always in the past
Constant refresh attempts
Performance degradation

Possible causes:

System clock is incorrect
Timezone mismatch
.env file not being updated

Solutions:

Check system time: date
Ensure system clock is accurate
Verify .env file permissions (must be writable)
Check disk space (file updates might fail)

.env File Not Updating

Symptoms:

Tokens refresh but .env still has old values
Manual edits to .env get reverted
Token expiry timestamp doesn’t update

Possible causes:

File permissions issue
Multiple instances running
.env file locked by another process

Solutions:

Check file permissions:
```
ls -la .env
chmod 644 .env
```
Ensure only one instance is running
Restart the MCP server
Check for file system errors

Server Falls Back to Client Credentials

Symptoms:

Server starts with user tokens but switches to client credentials
Limited API access after running
Higher rate limit errors

Possible causes:

User tokens became invalid
Token refresh failed
Access token expired and refresh token missing

Solutions:

Check server logs for token errors

Verify all token variables in .env:

EBAY_USER_ACCESS_TOKEN
EBAY_USER_REFRESH_TOKEN
EBAY_USER_TOKEN_EXPIRY

Re-run OAuth setup if tokens are missing
Ensure refresh token is valid

Invalid Token Format

Symptoms:

“Invalid token format” errors
Token validation fails
API calls return 401

Possible causes:

Token string got truncated
Extra spaces or newlines in .env
Token got corrupted during copy/paste

Solutions:

Re-run OAuth setup to get fresh tokens:
```
npm run setup
```
Check .env for formatting issues
Ensure no quotes around token values
Verify no line breaks in token strings

Token Management Best Practices

For Development

Local Development
Team Development

Recommended setup:

Use Sandbox environment
Store tokens in .env file
Add .env to .gitignore
Use interactive setup wizard
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

Getting Started

Authentication

Core Features

Guides

MCP Integration

Advanced

Support

​Token Types

Access Token

Refresh Token

​How Token Management Works

​Automatic Token Lifecycle

​Token Expiry Details

​Access Token Expiration

​Refresh Token Expiration

​Token Refresh Process

​When Refresh Happens

​How Refresh Works

​Monitoring Token Status

​Check Current Token Status

​Validate Tokens

​Server Logs

​Manual Token Operations

​Manually Refresh Tokens

​Regenerate Tokens

​Revoke Tokens

​Token Security

​Protecting Your Tokens

​Troubleshooting Token Issues

​Common Problems

​Token Management Best Practices

​For Development

​For Production

​Advanced Token Management

​Token Caching

​Preemptive Refresh

​Multiple Environments

​Next Steps

OAuth Setup

Client Credentials

Rate Limits

Troubleshooting

​Additional Resources

eBay Token Documentation

Security Best Practices

Configuration Guide

Error Handling

Token Types

How Token Management Works

Automatic Token Lifecycle

Token Expiry Details

Access Token Expiration

Refresh Token Expiration

Token Refresh Process

When Refresh Happens

How Refresh Works

Monitoring Token Status

Check Current Token Status

Validate Tokens

Server Logs

Manual Token Operations

Manually Refresh Tokens

Regenerate Tokens

Revoke Tokens

Token Security

Protecting Your Tokens

Troubleshooting Token Issues

Common Problems

Token Management Best Practices

For Development

For Production

Advanced Token Management

Token Caching

Preemptive Refresh

Multiple Environments

Next Steps

Additional Resources