TypeScript SDK

IntroCopy Anchor Link

The Walmart Seller API — Authorization SDK provides access to the Walmart Seller API — Authorization REST APIs.

OAuth token issuance for Walmart Marketplace, covering both v4 authorization flows in one contract:

1. Seller-direct (client_credentials) — a seller's own application exchanges its client credentials for a short-lived access token, then calls the v4 APIs with Authorization: Bearer <token>.
2. Solution-Provider delegated (authorization_code + PKCE, refresh_token, and Dynamic Client Registration) — a seller grants a Solution Provider's application access to their Marketplace account.

Both flows are served by the Authorization API as a stateless proxy to Walmart IAM : IAM remains the sole issuer; no secrets are stored and no tokens are signed here. Access tokens are opaque, Bearer-type, short-lived; refresh tokens (delegated flow) are rotated on use. Never log tokens.

One token endpoint, grant dispatchCopy Anchor Link

POST /auth/v4/token handles all three grants (client_credentials, authorization_code, refresh_token) via grant_type dispatch — the merged v4 contract ( for seller-direct, for delegated). This is why the two formerly separate specs (openapi.yaml + delegated-oauth.yaml) are now a single document: a path can carry exactly one post:, so one file makes the shared endpoint unambiguous for codegen and for the implementing controller.

PostureCopy Anchor Link

• Seller-direct is OAuth 2.0 : documents what IAM/Apigee already do. IAM cannot add new auth features for this flow, so client_credentials issues no refresh token, scope= is accepted-but-ignored (no down-scoping), and introspection (RFC 7662) / revocation (RFC 7009) / discovery (RFC 8414) are deliberately absent.
• Delegated is OAuth 2.1 : IAM already supports PKCE (S256), refresh rotation (~1-year TTL via offline_access), and Dynamic Client Registration (RFC 7591), so this flow specifies them properly.

The one modernization over /v3 shared by both flows is the access-token header: v4 uses the standard Authorization: Bearer and does not use WM_SEC.ACCESS_TOKEN (the gateway already tolerates Bearer).

Delegated-flow upstream gaps (, pending)Copy Anchor Link

GET /auth/v4/authorize documents the OAuth-2.1-correct target. Three of its guarantees depend on upstream changes that are not yet in place: iss emission (RFC 9207), exact redirect_uri enforcement, and server-side PKCE S256 enforcement (rejecting plain) are IAM / app-store responsibilities tracked in . the Authorization API validates the request-side invariants it can and redirects correctly; the full end-to-end guarantee lands when IAM + app-store ship those changes.

Pod Owner: Pod 0 — Core & Auth Implementation target: the Authorization API (proxy) → Walmart IAM

InstallationCopy Anchor Link

The SDK compiles to dist/ before it can be referenced — run its build script once in the SDK folder, then add it to your project by path:

npm install <path-to-sdk>

Quick StartCopy Anchor Link

Create one client and reuse it. Configure its behaviour through ClientOptions.

import {
  PkceMethod,
  ServerEnvironment,
  WalmartSellerApiAuthorizationClient,
} from "walmart-seller-api-authorization";

const client = new WalmartSellerApiAuthorizationClient({
  serverEnvironment: ServerEnvironment.Production,
  sellerAuthAuthorizationCode: {
    clientId: "YOUR_CLIENT_ID",
    redirectUri: "YOUR_REDIRECT_URI",
    pkce: PkceMethod.S256,
    promptForAuthorizationCode: (authorizationUrl, signal) => Promise.resolve("YOUR_AUTHORIZATION_CODE"),
  },
  sellerAuthClientCredentials: { clientId: "YOUR_CLIENT_ID", clientSecret: "YOUR_CLIENT_SECRET" },
  basicClientAuth: { username: "YOUR_USERNAME", password: "YOUR_PASSWORD" },
});

Nothing in ClientOptions is required — new WalmartSellerApiAuthorizationClient() compiles — and each option left out falls back to its default. serverEnvironment is spelled out above so the environment a call reaches is visible where the client is built rather than inherited silently.

From CommonJSCopy Anchor Link

The package ships both dialects from a single entry, so require works with full types. In a TypeScript CommonJS file use the import ... = require(...) form — a plain destructuring require runs fine but gives you any.

import sdk = require("walmart-seller-api-authorization");

const client = new sdk.WalmartSellerApiAuthorizationClient({
  serverEnvironment: sdk.ServerEnvironment.Production,
  sellerAuthAuthorizationCode: {
    clientId: "YOUR_CLIENT_ID",
    redirectUri: "YOUR_REDIRECT_URI",
    pkce: sdk.PkceMethod.S256,
    promptForAuthorizationCode: (authorizationUrl, signal) => Promise.resolve("YOUR_AUTHORIZATION_CODE"),
  },
  sellerAuthClientCredentials: { clientId: "YOUR_CLIENT_ID", clientSecret: "YOUR_CLIENT_SECRET" },
  basicClientAuth: { username: "YOUR_USERNAME", password: "YOUR_PASSWORD" },
});