Integration

Connect Suger to Alibaba Cloud Marketplace to list your SaaS products, manage offers, sync entitlements, and report usage — across both China (domestic) and international markets.

Overview

Alibaba Cloud Marketplace connects Alibaba Cloud customers with trusted SaaS providers and ISVs worldwide. Regardless of the region you sell in, the operational logic stays consistent with the other major clouds:

Prerequisites

To establish a secure handshake between Suger and Alibaba Cloud, gather four pieces of information from your Alibaba Cloud account:

• Alibaba Cloud Account ID — your unique root account Uid (aliyunUid).
• Access Key ID — the public identifier for your API credentials.
• Access Key Secret — the private key for API authentication.
• SPI Key — the Service Provider Interface key, used to verify security for notification events (such as a customer purchase).

You will also need the Region ID you sell in (e.g. cn-beijing for China, or an international region).

Connect

Link your Alibaba Cloud credentials to Suger to enable automated order management and revenue recognition.

1. Navigate to Settings > Integrations and locate the Alibaba Marketplace card. Click Connect.
2. Enter your Region ID, Cloud Account ID (root account Uid), Access Key ID, Access Key Secret, and SPI Key.
3. (Optional) Enter the Product Code(s) you want to list — these can also be configured later.
4. Click Create (or Verify) to validate the credentials and confirm the connection.

Manage settings

Once connected, you can fine-tune how Suger interacts with your Alibaba listings from the integration’s edit menu:

• Product Fetching — by default, Suger fetches all products under your Account ID. To limit this, manually enter specific Product Code(s).
• Metering Control — toggle Usage Metering Disabled if you need to pause usage reporting to Alibaba.
• Renewal Notifications — enable Entitlement End Soon alerts to notify your team by email (10–60 days in advance) when a buyer’s contract is approaching its end date.

Auth-Free URL redirection

Let your buyers reach your backend directly from the Alibaba Console without re-authenticating. When a buyer opens your service, Suger signs the request with your SPI Key and redirects the buyer to your Fulfillment URL with a token you verify on your side.

1. Configure fulfillment — set your fulfillment URL in the Alibaba Marketplace to point to the Suger service.

2. Redirection flow — when a buyer clicks to access your service, Suger resolves the entitlement, signs the request with your SPI Key, and redirects the buyer to your Fulfillment URL:

   https://<your-fulfillment-url>/?sugerEntitlementId=<id>&partner=alibaba&timestamp=<timestamp>&token=<token>

   Parameter	Value
   sugerEntitlementId	The Suger entitlement (contract) ID.
   partner	The literal string alibaba (lowercase).
   timestamp	The event time in RFC 3339 UTC, e.g. 2026-01-15T09:30:00Z.
   token	A 32-character lowercase-hex signature (see below).

3. Verify on your backend — recompute the signature from the query parameters and your SPI Key and compare it to token before you trust the redirect.

Validation contract

The token is a lowercase-hexadecimal MD5 digest of the UTF-8 bytes of the signed string. Build the signed string, hash it, and compare:

1. Take the redirect’s query string and remove the token parameter. Keep every other parameter in the exact order received — sugerEntitlementId, then partner, then timestamp. Do not sort or re-encode the parameters.
2. Append &key=<your SPI Key> to that string.
3. Compute md5(...) over the UTF-8 bytes and hex-encode it in lowercase.
4. Compare the result to the received token using a constant-time comparison.

So the string you hash is:

sugerEntitlementId=<id>&partner=alibaba&timestamp=<timestamp>&key=<SPI Key>

Worked example. With SPI Key my-spi-key, entitlement ent-abc123, and timestamp 2026-01-15T09:30:00Z, the signed string is:

sugerEntitlementId=ent-abc123&partner=alibaba&timestamp=2026-01-15T09:30:00Z&key=my-spi-key

and token = bd6b70b1b180ec9d0f8ed112d8b18129.

The SPI Key used to sign is the same SPI Key you configured on the integration. Keep it secret; anyone with it can forge a valid redirect.

Reference validators

Go

import (
	"crypto/md5"
	"crypto/subtle"
	"encoding/hex"
	"strings"
)

// validateRedirect verifies the Alibaba auth-free redirect token.
// rawQuery is the URL query string exactly as received, e.g.
// "sugerEntitlementId=ent-abc123&partner=alibaba&timestamp=2026-01-15T09:30:00Z&token=bd6b...".
func validateRedirect(rawQuery, spiKey string) bool {
	var received string
	kept := make([]string, 0)
	for _, p := range strings.Split(strings.TrimPrefix(rawQuery, "?"), "&") {
		if strings.HasPrefix(p, "token=") {
			received = strings.TrimPrefix(p, "token=")
			continue
		}
		kept = append(kept, p) // keep received order; do NOT sort
	}
	sum := md5.Sum([]byte(strings.Join(kept, "&") + "&key=" + spiKey))
	expected := hex.EncodeToString(sum[:])
	return subtle.ConstantTimeCompare([]byte(received), []byte(expected)) == 1
}

Python

import hashlib
import hmac

def validate_redirect(raw_query: str, spi_key: str) -> bool:
    received = ""
    kept = []
    for p in raw_query.lstrip("?").split("&"):
        if p.startswith("token="):
            received = p[len("token="):]
        else:
            kept.append(p)  # keep received order; do NOT sort
    string_to_sign = "&".join(kept) + "&key=" + spi_key
    expected = hashlib.md5(string_to_sign.encode("utf-8")).hexdigest()
    return hmac.compare_digest(received, expected)

TypeScript

import { createHash, timingSafeEqual } from "node:crypto";

function validateRedirect(rawQuery: string, spiKey: string): boolean {
  let received = "";
  const kept: string[] = [];
  for (const p of rawQuery.replace(/^\?/, "").split("&")) {
    if (p.startsWith("token=")) received = p.slice("token=".length);
    else kept.push(p); // keep received order; do NOT sort
  }
  const expected = createHash("md5")
    .update(kept.join("&") + "&key=" + spiKey, "utf8")
    .digest("hex");
  const a = Buffer.from(received);
  const b = Buffer.from(expected);
  return a.length === b.length && timingSafeEqual(a, b);
}

Edit / Delete

You can update your Account ID or Product Codes at any time by editing the integration. To rotate security-sensitive keys (such as the Access Key Secret or SPI Key), delete the integration and reconnect with the new credentials.

Deleting the integration immediately erases all stored API and SPI keys from Suger and stops product sync, entitlement processing, and metering. This won’t delete your products on Alibaba, but automated syncing and entitlement tracking stay paused until you manually reconnect.