Definitive Guide to SellerLegend OAuth Token Management

1. Why OAuth Tokens Matter

When you connect to SellerLegend's API, you don't log in with your email/password. Instead, you use tokens:

• Access Token — the "front-door key." Lets you make API calls (e.g. get orders, sales statistics, inventory). Short-lived (~15 days).

• Refresh Token — the "spare key." Lets you request a brand new access token when the old one expires. Longer-lived (~30 days).

This two-key system makes sure that:

• If your access token leaks, it will expire quickly.
• You don't have to ask the user to log in again every two weeks.

Think of it like this: Access token = hotel room keycard. Refresh token = your ID at the reception desk to get a new keycard.

2. Token Lifecycle in SellerLegend

• Access token validity: 15 days
• Refresh token validity: 30 days
• Every time you refresh, SellerLegend gives you:
  • a new access token
  • and a new refresh token
• This means you must always overwrite your stored (previous) refresh token with the new one. Otherwise, you'll get stuck using a revoked refresh token.

3. How to Obtain Your First Tokens

1. Redirect the user (or yourself) to the authorize URL within SellerLegend: https://app.sellerlegend.com/oauth/authorize Include your client_id, redirect_uri, etc.

2. After logging in and granting access in the Authorize screen, SellerLegend redirects back with a code.

3. Exchange that code for tokens at: https://app.sellerlegend.com/oauth/token with:

   • grant_type=authorization_code
   • client_id=...
   • client_secret=...
   • redirect_uri=...
   • code=...

4. The response to the Token request gives you:

   {
     "access_token": "abc...",
     "refresh_token": "xyz...",
     "expires_in": 1296000,
     "token_type": "Bearer"
   }

   The expires_in value is ~15 days in seconds.

4. Using and Refreshing Tokens

Making API calls

Send the access_token in the Authorization header of any API request:

GET /api/sales/per-day-per-product ...
Authorization: Bearer {access_token}

Refreshing before expiry

When your access token is about to expire, call:

POST https://app.sellerlegend.com/oauth/token

with:

• grant_type=refresh_token
• client_id
• client_secret
• refresh_token (your current one)

Response returns new access and refresh tokens.

WARNING

Always overwrite both tokens in your storage.

5. Best Practices (Lessons Learned)

• Refresh early — Don't wait until the access token expires. Refresh ~1 minute before to avoid downtime.
• Atomic token storage — Save tokens to a file (e.g., tokens.json) in one step. If you crash mid-write, you won't corrupt your tokens.
• Always overwrite refresh token — Every refresh gives you a new one. Using an old one after expiry = invalid_grant.
• Guard against race conditions — If multiple parts of your app refresh at once, only let one process do it and share the result.
• 401 recovery — If you hit the API and get a 401 "Unauthorized", trigger a refresh once and retry the request.

6. Common Pitfalls

Problem	Symptom	Fix
Wrong endpoint	404 or 500 when refreshing	Use /oauth/token (not /api/oauth/token in most cases)
Tokens not saved	Works once, fails later	Ensure you write tokens.json after every refresh
Old refresh token reused	invalid_grant	Always overwrite refresh token with the new one
Redirect URI mismatch	invalid_grant on first login	Redirect URI in code must exactly match what's registered in SellerLegend (including port and /callback)
Concurrency issue	Intermittent token failures	Add a refresh lock or "in-flight promise" to serialize refresh calls

7. Practical Example (Node.js Express)

Here's the refresh function used in the local server:

let inFlight = null;

async function getTokens() {
  const t = load();
  if (Date.now() < t.expires_at) return t;

  if (!inFlight) {
    inFlight = refresh(t.refresh_token).then(newT => {
      saveAtomically(newT);
      return newT;
    }).finally(() => { inFlight = null; });
  }
  return inFlight;
}

8. Final Checklist

• Store tokens securely (file, DB, vault).
• Always overwrite both tokens after refresh.
• Refresh before expiry, not after.
• Handle 401 Unauthorized by refreshing once.
• Double-check your redirect_uri and client credentials.

Takeaway

OAuth with SellerLegend is predictable once you know the rules. The tricky part is remembering that refresh tokens rotate too — not all APIs do this. If you always overwrite and refresh a little early, your integration will run smoothly.