Authentication management

Overview

Walmart APIs require each user to be authenticated before making API requests. Authentication verifies that a user is authorized to access a system, and determines the user's level of access.

An access token is a string that authenticates a user and specifies the user's access and authorization level for making API requests. The Walmart 1P Supplier APIs use OAuth 2.0 bearer tokens for token-based authentication.

For security reasons, each access token has a limited lifespan, and is invalid after expiration. You can generate access tokens as needed, and as frequently as before each request, but it is best practice to use an existing access token until it is no longer valid.

Use this API to:

• Create an access token with the client credentials grant

Base URLs

• Production: https://api-gateway.walmart.com
• Sandbox: https://sandbox.walmartapis.com

Audience

• First‑party suppliers and their solution providers

How it works

1. Generate a Base64‑encoded string from your clientId:clientSecret.
2. Call POST /v3/token with Content-Type: application/x-www-form-urlencoded and body grant_type=client_credentials.
3. The service returns an access_token, token_type, and expires_in seconds.
4. Use the token in subsequent API calls in the WM_SEC.ACCESS_TOKEN header, until it expires.

Before you begin

• Get your client ID and client secret from Walmart.
• Be prepared to rotate credentials on a regular schedule.
• Store secrets in a secure vault. Do not check them into source control.

About generating your authorization value

Before you generate an access token, you must generate a Base64-encoded authorization value using the Client ID and Client Secret provided in your API keys. The two keys are combined into a single encoded string.

You only need to encode your authorization value once. It is a secured value that you can share among users. You can even include it in an app as an enumerated value (enum) for convenient reuse in API requests.

Obtaining your existing API keys

If you are using an existing account, you can get these values from your system administrator or development management. Your API keys will typically look like this:

Client ID: db7fdea5-013b-41fe-8960-4chf11196673
Client Secret: DehsAyrzXZK8bARud70Ou…8Sdm0HpijhQEFqOj4dUBXCd-2SxAaLg6C6XokjQMu8cGZvx3CxMdqiQ

The Client ID is the public key. You can share this value with other users.

The Client Secret is your private key. Do not share it with others; treat it as a sensitive password.

Creating new API keys

If you do not yet have API keys, create them using the following procedure:

1. Sign in to the Developer Portal.
   Check with your system administrator or development management for your exact URL.
2. Select My Account.
3. Select 1P Supplier.
4. Sign in to your account with your email and password.
5. Create the Client ID and Client Secret values on the API keys page.

Generating a Base64-encoded authorization value

To generate your authorization value, encode your Client ID and Client Secret values in Base64 using the UTF-8 character set and Unix newline separators. Any Base64 encoder may be used, such as a programmatic encoder or a Base64 encoder web site.

Note:
Be cautious when using Base64 encoding websites, as your client secret needs to be protected and treated as a password.

Use the format: <Client ID>:<Client secret>

Example combined: db7f6eb5-01hb:DehsbzdUBXCd

The following snippet shows one way to encode your authorization value using Python:

string_to_encode = "db7fdea5-013b:DehsbzdUBXCd"
bytes_to_encode = string_to_encode.encode('utf-8')
encoded_bytes = base64.b64encode(bytes_to_encode)

The resulting encoded value is a string, such as DE2Yi00MWZlLTg5NjAtNGTk2YNlFNdThjR1p2eDND

Required headers

Authentication model

The token endpoint uses HTTP Basic on the request and returns an OAuth 2.0 Bearer token. Send the returned access token in downstream Walmart API calls using header WM_SEC.ACCESS_TOKEN: <access_token>.

Environments

• Sandbox uses the same path and headers. Tokens are valid only in the environment where they are created.
• Production returns live tokens scoped for production use.

Rate limits and retries

If you receive 429 Too Many Requests, back off and retry with exponential delay. Avoid requesting a new token for every call. Cache and reuse tokens until expires_in.

Errors

Handle HTTP status codes and error bodies.

Endpoint

Create an access token

POST /v3/token

Creates an access token using the client credentials grant.

Headers

• Authorization: Basic <Base64(clientId:clientSecret)>
• WM_QOS.CORRELATION_ID: <uuid>
• Content-Type: application/x-www-form-urlencoded
• Accept: application/json (optional)
• WM_CONSUMER.CHANNEL.TYPE: <channel> (optional)
• WM_MARKET: CA (required for Canada suppliers)

Request body (x‑www‑form‑urlencoded)

grant_type=client_credentials

cURL example

curl -X POST 'https://api-gateway.walmart.com/v3/token' -H 'Authorization: Basic <BASE64_CLIENTID_COLON_CLIENTSECRET>' -H 'WM_QOS.CORRELATION_ID: 6b007f0a-3171-4135-86b5-db805f34e13b' -H 'Content-Type: application/x-www-form-urlencoded' -H 'Accept: application/json' --data-urlencode 'grant_type=client_credentials'

Success response

{ "access_token": "eyJraWQiOiIzZj…VhYTFmNS1hYWE5LTQzM", "token_type": "Bearer", "expires_in": 900
}

Unauthorized error example

{ "error": [ { "code": "UNAUTHORIZED.GMP_GATEWAY_API", "field": "UNAUTHORIZED", "description": "Unauthorized", "info": "Unauthorized token or incorrect authorization header. Verify correct format: Authorization: Basic Base64Encode(clientId:clientSecret).", "severity": "ERROR", "category": "DATA", "causes": [], "errorIdentifiers": {} } ]
}

Best practices

• Cache tokens until expiration. Refresh only when needed or on 401.
• Use a unique WM_QOS.CORRELATION_ID for each call.
• Use TLS 1.2 or higher. Never send credentials over HTTP.
• Limit who can read client secrets. Rotate on schedule and when compromised.
• Avoid logging secrets or full Authorization headers. Mask or redact.

Security and privacy

• Do not include PII in URLs or logs.
• Store secrets in a secure vault. Enforce least privilege.
• Use short token lifetimes and monitor failed authentication attempts.