Designing Secure Open Platform APIs: OAuth2, Signing, and Best Practices

After integrating many e‑commerce open platforms (Taobao, JD, Kuaishou, Douyin), I realized that even though the integration itself is straightforward, a solid design pattern for open platform APIs is essential.

Key Concerns for Open Platforms

Usability: simple, self‑descriptive request parameters for quick onboarding.

Security: protect user data exposed to the internet.

Stability: ensure reliable service for upstream providers.

Service Provider Application

An open platform consists of three main parts:

Integration guide – helps providers connect to the platform.

API documentation – assists developers in implementing business functions.

Application – the provider’s identity on the platform, enabling rate limiting and permission control.

The first step for a provider is to create an application, which yields an appid, appsecret, and an authorization callback URL.

Basic Attributes

appid

: unique identifier of the provider application. appsecret: secret key used for signing and identity verification.

Authorization callback URL: endpoint invoked after user consent.

Authorization Process

Authorization is not granted by the platform to the provider directly; instead, end users (e.g., a shop owner) must authorize the provider application to access their data.

Three roles are required for authorization:

Open platform – presents the authorization page and redirects to the provider’s callback URL with the granted data.

Customer – completes the consent on the platform’s page.

Provider application – receives the callback, binds the user, and stores the authorization information.

Alternatively, the provider can authenticate using appid + appsecret when no third‑party user consent is needed.

OAuth2 Authorization Mechanism

OAuth2

is the de‑facto standard for web authorization (e.g., GitHub login, WeChat public account authorization). For a deeper dive, see my previous article on OAuth2 and Spring Security.

Request Parameters

Parameters are divided into two categories:

System parameters – required for every API call (e.g., appid, appsecret, timestamp, sign).

Business parameters – specific to the business operation (e.g., status for order queries).

System parameters are passed via URL query strings, while business parameters are sent in the request body (commonly application/json or application/x-www-form-urlencoded) and must also participate in the signature.

Request Signing

Signing prevents tampering. Common algorithms include MD5, SHA, or asymmetric encryption for high‑security scenarios. A typical signing formula is:

sign = appsecret + appid + timestamp + sorted_business_params + appsecret

Pseudocode

String appid = "abcd";
String appsecret = "12345";
Long timestamp = 948758686L;
// Ordered map, sorted by key
Map<String, Object> requestBody = new TreeMap<>();
requestBody.put("a", 1);
requestBody.put("b", 21);
requestBody.put("c", 2);
// Convert to JSON string
String jsonBody = JSON.toJSONString(requestBody);
String sign = DigestUtils.md5hex(appsecret + appid + timestamp + jsonBody + appsecret);

Signature Verification

Verification mirrors the generation process:

String appid = request.getParameter("appid");
String appsecret = request.getParameter("appsecret");
Long timestamp = request.getParameter("timestamp");
// Extract business parameters and sort them
Map<String, Object> requestBody = new TreeMap<>(JSON.parseObject("post_body"));
String jsonBody = JSON.toJSONString(requestBody);
String sign = DigestUtils.md5hex(appsecret + appid + timestamp + jsonBody + appsecret);
String originSign = request.getParameter("sign");
if (Objects.equals(sign, originSign)) {
    // verification succeeded
} else {
    // verification failed
}

Conclusion

The above outlines a practical design pattern for open platform APIs, covering usability, security, authorization flows, parameter handling, and concrete signing/verification implementations. Future posts will explore SDK design for such platforms.