Authentication

Warehouse /

Authentication

To authenticate an API call successfully, pass a Consumer ID and digital signature in the header for every API call.

Register as a Walmart Warehouse Supplier to receive a Consumer ID and Private Key. Log into the Supplier Center to obtain these items. Use the Consumer ID and Private Key, along with other required header parameters, to generate a digital signature.

Integration Process

  1. Test out a simple API call, such as GET Feed Status.
  2. Generate a digital signature. Note: The digital signature will expire in 15 minutes; regenerate the signature using the same procedure. There are two ways to generate a digital signature:

    Using the executable JAR file will eliminate a majority of authentication issues.

  3. Pass the following header keys to authenticate your API call:
    Name Description Required Example
    WM_SVC.NAME
    Walmart Service Name
    Yes
    Walmart Gateway API
    WM_QOS.CORRELATION_ID
    A unique ID which identifies each API call and used to track and debug issues; use a random generated GUID for this ID
    Yes
    1234hfvgtr
    WM_SEC.TIMESTAMP
    The Epoch timestamp
    Yes
    1443748249449
    WM_SEC.AUTH_SIGNATURE
    The vendor’s digital signature, generated by running the JAR file or custom generation code
    Yes
    9fg3TPeRt0WSGbXNGGj4kSQ9L6PMBX/q+ovdy9bDQfvdhY
    s8NoEsjRX4fD7UNIHTddgkmSVqAqeIIHlaLcRIl0Y4DcJqQY
    HL27LiWlsm91nYodGssWTKsOq6dJfUHEy95M4zXFGWDDh
    bHYCor28SCV/g/JdEQybGkcX9Zj5aDyg=
    WM_CONSUMER.CHANNEL.TYPE
    A unique ID to track the consumer request by channel
    Yes for V3, optional for V2
    0f3e4dd4-0514-4346-b39d-… use the Consumer Channel Type
    received during onboarding
    WM_CONSUMER.ID
    A unique ID required to access the API
    Yes
    Get the Consumer ID from Developer Center after logging in

    If you are having trouble connecting to Developer Center, refer to Troubleshooting.

  4. Make sure the call does not throw a 400 or 401 error. For more information, refer to Error Codes.
    • If a 400 HTTP status code is received, validate the mandatory headers and all mandatory query or path parameters.
    • If a 401 HTTP status code is received, verify the digital signature.
Header Sample
WM_SVC.NAME: Warehouse Supplier Services
WM_QOS.CORRELATION_ID: 123456abcdef
WM_SEC.TIMESTAMP: 1438147839
WM_SEC.AUTH_SIGNATURE: 7QzL9PeRt0WSGbXNGGj4kSQ9L6PMBX/q+ovdy9bDQfvdhYs8NoEsjRX4fD7UNIHTddgkmSVqAqeIIHlaLcRIl0Y4DcJqQYHL27LiWlsm91nYodGssWTKsOq6dJfUHEy95M4zXFGWDDhbHYCor28SCV/g/JdEQybGkcX9Zj5aDyg=
WM_CONSUMER.ID: a20ac266-9add-4fc7-9392-fec303f5155c
WM_CONSUMER.CHANNEL.TYPE: 0f3e4dd4-0514-4346-b39d-af0e00ea
Content-Type: multipart/form-data
Accept: application/xml

Generating a Digital Signature Using an Executable JAR File (Recommended):

To generate a digital signature using the executable JAR file, follow these steps:

  1. Download Java 6.0 or greater. If it is not installed on your computer, go to: https://java.com/en/download
  2. Download the executable JAR file: wsdigitalSignatureUtil-1.0.0.jar
  3. Use the following command to run the executable JAR file:

    java -jar DigitalSignatureUtil-1.0.0.jar DigitalSignatureUtil {requestUrl} {consumerId} {privateKey} {requestMethod} {filePath}

The executable JAR file uses five parameters; see the table below:

Name Description Required
requestUrl
The full URL to call, including path and query parameters
Yes
consumerId
The Consumer ID retrieved from Developer Center after login
Yes
privateKey
The vendor’s Base-64-encoded, PKCS#8 stored Private Key
Yes
requestMethod
Use method GET (all capital letters) to call this API
Yes
filePath
The absolute (full) path of the file desired for the digital signature and timestamp. The digital signature and timestamp can also be viewed in the console.
Yes
Sample call to the executable JAR
java -jar DigitalSignatureUtil-1.0.0.jar DigitalSignatureUtil https://api-gateway.walmart.com/v3/feeds/d4885da4-9bc1-4296-b26f-57e3cb0e0fc9?includeDetails=true 9a4d7659-100c-4d5e-a6b0-26faad4c9132 MIICeAIBADANBgkqhkiG9w0BAQEFAA... GET HelloWorld

Generate a Digital Signature Using Self-Written Code

To get the digital signature using self-written code, follow these steps:

    1. Get the Consumer ID and Private Key from the Developer Portal.
    2. Get the full URL you wish to call, including any path and query parameters.
    3. Use the GET method to construct an input for the digital signature.

Use the structure listed below:

The Consumer ID_ + “\n” + the URL of the API call + “\n” + the request method of the API call in all capitals + “\n” + the current Unix epoch timestamp + “\n”

** Note: The order of the parameters and the line returns \n are important to generate the signature properly; see the sample code in the right pane. **

  1. Generate the byte array of the structured data listed in step 3 using the following steps:
    1. Decode the byte array with Base-64.
    2. Encode the resulting value using PKCS#8 to represent your Private Key.
      Libraries in various languages offer the ability to identify that the Private Key is in PKCS#8 format and not in other conflicting formats such as PKCS#1.
    3. Use this byte representation of the Private Key to sign the data using SHA-256 with RSA.
    4. Encode the generated digital signature using Base 64.
  2. Use the generated digital signature and Unix epoch timestamp to make an API call.

Troubleshooting

New users can experience difficulty when trying to integrate with the platform for the first time. Typically, errors occur when incorrect headers are generated (such as the timestamp or authentication signature). To avoid errors, use the headers listed in the header samples displayed in each corresponding section.

Testing the API Calls

To accelerate development, you can use an online tool such as the Google Chrome Advanced REST Client App (ARCA), Postman, etc.

To test your API calls using the ARCA, follow the steps below:

  1. Enter the URL: https://api-gateway.walmart.com/v3/feeds?feedType=SUPPLIER_FULL_ITEM
  2. Select GET from the drop-down menu.
  3. Configure the headers as listed in the table under ‘Integration Process’.
  4. Click Send.

If basic API calls are successful from the ARCA but are not successful from the self-written code, the problem lies in the self-written code. If the calls fail from the ARCA, there is a problem with the headers in the call.

Troubleshooting Hints

  • If the call from the ARCA succeeds, the headers are correct. However, if the call fails, examine the headers.
  • If the call from the ARCA fails and you are not using the executable JAR file, generate the headers using the executable JAR file and try again. If the call now succeeds, either start using the executable JAR file in place of the self-written authentication code, or adjust the self-written code to generate the headers correctly.
  • If the call from the ARCA fails while using the executable JAR file, generate a new set of credentials from the Developer Portal and retry with the new credentials. This ensures that the credentials are not obsolete and that you have not reset the Private Key recently.
  • If the ARCA is configured correctly and the newest credentials are being used, but errors persist, contact Partner Support.