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 an 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, // ~15 days in seconds
"token_type": "Bearer"
}


4. Using and Refreshing Tokens

Making API calls

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

Refreshing before expiry

When your access token is about to expire, call:

with:

• grant_type=refresh_token

• client_id

• client_secret

• refresh_token (your current one)

Response returns new access and refresh tokens.
⚠️ Always overwrite both 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

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;
}

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