How a Key Management Gateway Secures Third‑Party API Integrations

Background

With the growth of internet applications, platforms often need to integrate multiple third‑party services such as payment (Alipay, WeChat Pay) or map APIs. These integrations rely on OpenAPI interfaces that require each vendor to provide signing rules and encrypted keys, leading to inconsistent security across providers.

Problem

Developers frequently embed keys directly in code or configuration files, making them visible to anyone with repository access. Even when keys are stored in a KMS, developers can still retrieve them at runtime, log them, or misuse them, creating significant risk of key leakage.

Key Management Solution

Introducing a centralized Key Management System (KMS) isolates key storage from developers. Business code calls the KMS to obtain keys, reducing direct exposure. However, developers can still extract keys via debugging, so additional controls are needed.

Traditional Solution

Before the gateway, services fetched keys directly, performed signing, and sent requests, leaving the business side responsible for both key handling and API logic.

Ideal Solution

The ideal model separates three roles: the service provider, the service consumer, and the key storage entity. The consumer never sees raw keys; it requests the gateway to sign and encrypt requests, while the provider remains unaware of the consumer’s internal logic.

Key Gateway Architecture

The gateway combines key management and an outbound proxy, providing signing, encryption, token handling, and request forwarding. It supports simple signing (AppKey + AppSecure) and two‑step verification (token acquisition + signing).

Key storage can be via configuration files (high risk) or KMS (lower risk). The gateway stores keys in KMS and retrieves them as needed, preventing developers from hard‑coding secrets.

Signing Module

The core signing module validates requests, generates signatures, and encrypts payloads. Simple signing uses a static AppKey/AppSecure pair, while two‑step verification first obtains a token before signing.

{
  "appKey": "appKey",
  "data": "123456",
  "sign": sha256('data=xxxx×tamp=xxxxx'+AppSecure)
}

Custom Mode

To avoid repetitive development‑test‑deploy cycles, a custom mode lets users write JavaScript expressions that implement signing logic directly in the gateway. The gateway provides built‑in sorting and cryptographic functions.

Signature Code Example

function (reqHeaders, reqParams, reqBody, AppKey, AesKey, AesIV, PrefixUrl, TokenUrl) {
  var ts = reqBody.get('timestamp');
  var token = token_load();
  if (!token) {
    var reqData = {
      "appKey": AppKey,
      "data": base64_encode(aes_cbc_pkcs5_encrypt(AesKey, '{"appKey": "'+AppKey+'"}', AesIV)),
      "timestamp": ts
    };
    reqData["sign"] = sha256('appKey='+AppKey+'&data='+reqData["data"]+'×tamp='+ts).toUpperCase();
    var respObj = JSON.parse(http_post_json(TokenUrl, reqData, {}));
    if (respObj["data"]["accessToken"]) {
      token = "Bearer "+respObj["data"]["accessToken"];
      token_save(token, respObj["data"]["expireTime"]);
    }
  }
  reqHeaders.set("Authorization", token);
  reqHeaders.setURI(PrefixUrl + reqHeaders.getURI());
  var originData = reqBody.get('data');
  var enData = base64_encode(aes_cbc_pkcs5_encrypt(AesKey, originData, AesIV));
  reqBody.set("appKey", AppKey);
  reqBody.set('data', enData);
  var sign = sha256(reqBody.buildSignStr()).toUpperCase();
  reqBody.set('sign', sign);
}

Response Handling

function (respBody, AppKey, AesKey, AesIV, PrefixUrl, TokenUrl) {
  if (401 == respBody["code"]) {
    token_delete();
  }
  if (respBody["data"]) {
    respBody["data"] = aes_cbc_pkcs5_decrypt(AesKey, base64_decode(respBody["data"]), AesIV);
  }
}

Advanced Features

The gateway supports multi‑tenant isolation, versioned configuration, and role‑based access control (gateway admin, tenant admin, tenant developer). Each tenant receives its own AppKey, and configurations are versioned to allow safe rollbacks.

Exception Handling

The gateway handles third‑party timeouts, configuration/key retrieval failures, and deployment/restart scenarios. Timeouts are configurable per provider, and the system can fall back to cached configurations if remote fetch fails.

Conclusion

The key‑gateway acts as a middleware that centralizes key management, signing, and error handling, improving security and operational efficiency for large‑scale API integrations. Ongoing work focuses on further reducing integration effort while maintaining stability.