JD API Authentication and Signature Mechanism: A Complete Guide for Secure Integration

In the previous article, we completed the registration of a JD Open Platform account and the creation of an application, laying the groundwork for subsequent API integration. This article will dive deep into the authentication and signature mechanism of JD APIs, covering:

1. Why authentication is necessary

2. Overview of system and security parameters

3. Principles and examples of the signature algorithm

4. OAuth2.0 dynamic token acquisition process

5. Common issues and best practices

By mastering these topics, you will be able to securely and reliably invoke various interfaces of JD Open Platform, ensuring readiness for real-world scenarios.

1. Why Is Authentication Necessary?

The JD Open Platform provides access to critical e-commerce business data such as inventory, orders, customer details, etc. Due to the sensitivity of this data, the system must ensure:

• Request authenticity: Only authorized applications can make calls

• Data integrity: Prevent tampering during transmission

• Auditability: Every call must be traceable to a specific AppKey and user

The authentication and signature mechanisms are designed specifically to meet these requirements.

2. System and Security Parameters

When calling any JD Open Platform API, you must include a set of common system parameters in addition to business parameters to ensure a standardized and secure request.

• For platform-level APIs that do not require user authorization, access_token may be omitted.

These parameters are used alongside business parameters to generate a signature.

3. Signature Algorithm Principles and Code Example

JD Open Platform uses MD5, HMAC-MD5, or HMAC-SHA256 algorithms for request signing. The process consists of five key steps:

Step 1: Collect All Parameters

Include all system and business parameters except for the sign parameter itself. Skip any parameters with None or empty values.

Step 2: Sort Parameters Alphabetically

Sort all parameter key-value pairs in ascending ASCII order by key.

Step 3: Concatenate into a Signature Base String

• MD5 signature (default):

  signature_base = AppSecret + key1 + value1 + key2 + value2 + ... + AppSecret
  sign = MD5(signature_base).toUpperCase()
  

• HMAC-MD5 or HMAC-SHA256 (optional):

  signature_base = key1 + value1 + key2 + value2 + ...
  sign = HMAC_ALGO(AppSecret, signature_base).toUpperCase()
  

Step 4: Generate the Digest

Apply the specified algorithm (MD5 or HMAC) to the signature base string to generate a hexadecimal digest.

Step 5: Convert to Uppercase and Attach to the Request

The final signature string should be in uppercase and passed as the sign parameter.

Python Signature Code Example

import hashlib
import hmac
import json
def generate_sign(params: dict, app_secret: str, algo: str = 'MD5') -> str:
items = sorted((k, v) for k, v in params.items() if v is not None and k != 'sign')
if algo.upper().startswith("HMAC"):
base = ''.join(f"{k}{v}" for k, v in items)
hash_func = hashlib.md5 if algo.upper() == 'HMAC-MD5' else hashlib.sha256
digest = hmac.new(app_secret.encode('utf-8'), base.encode('utf-8'), hash_func).hexdigest()
else:
base = app_secret + ''.join(f"{k}{v}" for k, v in items) + app_secret
digest = hashlib.md5(base.encode('utf-8')).hexdigest()
return digest.upper()
params = {
"method": "jingdong.sku.get",
"app_key": "YOUR_APP_KEY",
"timestamp": "2025-04-29 10:00:00",
"v": "2.0",
"360buy_param_json": json.dumps({"skuId": 123456})
}
app_secret = "YOUR_APP_SECRET"
sign = generate_sign(params, app_secret)
print("Signature =", sign)

4. OAuth2.0 Dynamic Token Acquisition

For user-authorized APIs (such as order queries or user information), in addition to the application-level signature, you must also include an access_token. JD uses the standard Authorization Code flow for OAuth2.0:

Step 1: Direct the User to Grant Authorization

Redirect the user to:

https://oauth.jd.com/oauth/authorize
?client_id=YOUR_APP_KEY
&response_type=code
&redirect_uri=YOUR_CALLBACK_URL

Upon login and consent, JD will redirect the browser to your redirect_uri with a code parameter.

Step 2: Exchange Code for Access Token

Your server sends a POST request to JD:

POST https://oauth.jd.com/oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&client_id=YOUR_APP_KEY
&client_secret=YOUR_APP_SECRET
&code=AUTHORIZATION_CODE
&redirect_uri=YOUR_CALLBACK_URL

Response:

{
"access_token": "USER_ACCESS_TOKEN",
"refresh_token": "REFRESH_TOKEN",
"expires_in": 86400
}

Step 3: Refresh the Token

Before the access_token expires, use the refresh_token to obtain a new token pair:

grant_type=refresh_token
&client_id=YOUR_APP_KEY
&client_secret=YOUR_APP_SECRET
&refresh_token=REFRESH_TOKEN

Security Guidelines

• Keep client_secret and refresh_token confidential and never expose them on the frontend

• Use HTTPS for all requests to prevent man-in-the-middle attacks

• Store tokens securely and implement automated refresh logic

5. Common Issues and Best Practices

Signature Errors

• Missing or incorrectly sorted parameters

• Inconsistent hashing algorithm usage

• Time drift: make sure timestamp is within 5 minutes of JD server time

401 Unauthorized

• access_token expired or invalid — re-authorize or refresh

• Application lacks required API permissions — check your app settings

403 Forbidden

• Rate limits exceeded — apply for higher limits via JD console

• API permission not yet approved — submit the necessary application

Avoiding Duplicate Requests

• Implement idempotency at the business logic level

• Avoid using random values in the signature — ensure consistent signing for the same parameters

6. Conclusion

JD’s API authentication and signature mechanism is the foundation for ensuring data security and request validity. Understanding the required parameters, mastering the signature algorithm, and handling the OAuth2.0 flow are essential for any application integrating with JD Open Platform. For maintainability and scalability, consider encapsulating the signing and authentication logic into middleware or utility modules to simplify integration and enhance security.

Articles related to APIs :

• Complete Guide to Accessing the JD Open Platform (JOS)

For seamless and efficient access to the Jingdong API, please contact our team : support@luckdata.com