Three Patterns of API Signature Verification — And How the Third One Wasted Our Afternoon

You call a third-party API, the signature keeps failing — then you realize the docs never explained it properly

True story. This afternoon, we were integrating a DNS management platform API to automatically create DNS records. The docs said: "Uses MD5 signature verification."

Sounds simple, right? Concatenate parameters, append the secret key, MD5 it, done.

We did exactly that. List endpoint worked. Query endpoint worked. Create record — signature error.

Two hours of debugging followed.

Three Common API Signature Patterns

Before diving into our pitfall, let me explain the three main approaches to API signature verification.

Pattern 1: Key-Append (Most Common)

The most intuitive approach, used by most Chinese payment APIs.

sign = md5(param1=value1&param2=value2 + secretKey)

Sort all parameters alphabetically into a string, append the secret key at the end, then MD5 the whole thing. WeChat Pay, Alipay Open Platform — all follow this pattern.

Pros: simple and straightforward. Cons: the key directly participates in the hash; if the hash algorithm is compromised (MD5 is theoretically not secure enough), the key could be at risk.

Pattern 2: HMAC (Most Secure)

sign = HMAC-SHA256(secretKey, param1=value1&param2=value2)

AWS, Google Cloud, Azure all use this. The key serves as the HMAC key, never directly concatenated into the string.

Highest security, but also highest implementation complexity — you need to handle canonicalized requests, timestamps, nonces, and a bunch of other things. AWS Signature V4 docs are long enough to use as a pillow.

Pattern 3: Key-As-Sorted-Parameter (The Sneaky One)

sign = md5(ALL parameters INCLUDING secretKey sorted alphabetically together)

Note the difference: here the secret key is NOT appended at the end. Instead, it's treated as a regular parameter and sorted alphabetically with everything else.

Example with these parameters:

domain=example.com
line=default
secretKey=abc123
top=A
value=1.2.3.4

The signature string is: domain=example.com&line=default&secretKey=abc123&top=A&value=1.2.3.4

NOT: domain=example.com&line=default&top=A&value=1.2.3.4abc123

See the difference? In the first one, secretKey sits between line and top (alphabetically, s is between l and t). In the second, secretKey is appended at the end.

This is exactly what trapped us for half a day.

Why Did the List Endpoint Work But Create Failed?

This is the most elegant part of the trap.

The list endpoint (Record.List) has very few parameters — maybe three or four. By coincidence, after alphabetical sorting, secretKey happened to end up last. So whether you "append at the end" or "sort with everything," the signature result is identical.

Pure coincidence.

But the create endpoint (Record.Create) has seven or eight parameters, some starting with letters after s (like top, value). Now the two algorithms produce different signatures.

This "some endpoints work, some don't" scenario is the hardest to debug — because you think your signature logic is correct (the list endpoint passed!), so you waste time checking parameter formats, encoding, HTTP headers, and other completely irrelevant things.

How Did We Fix It?

The solution was simple: find the API's Swagger/OpenAPI documentation, carefully read the signature section, and spot that critical fine print — "secretKey participates in alphabetical sorting as a regular parameter."

Lessons learned:

1. Don't guess the signature algorithm. Even if you "roughly know it's MD5," the exact concatenation method without reading docs is gambling.
2. One endpoint passing doesn't mean your logic is correct. Test with the endpoint that has the most parameters, not the least.
3. Find the Swagger first. Many platforms' main docs are terribly written, but Swagger definitions are machine-generated and often more accurate.
4. Print the pre-hash string. Don't just compare final MD5 values; print the raw string before hashing and compare character by character.
5. Watch for integer vs. string types. A field marked as int32 in Swagger might need to be "0" (string) in the signature string, not 0 (number). Type mismatch = wrong signature.

Why Is This Worth a Full Article?

Because this is an extremely common but rarely discussed problem.

Big platform APIs (AWS, Google, Stripe) have thorough documentation with complete examples and SDKs. But countless small-to-medium platforms — especially Chinese security products, CDN services, and cloud hosting providers — have inconsistent documentation quality. The signature section often boils down to one sentence: "Uses MD5 signature," with zero details on how to concatenate.

Yet signature verification is the foundation of API security. Can't get the signature right? Everything after that is moot.

So next time you hit a "signature error," don't immediately blame your code. Ask three questions first:

1. Is the key appended at the end, or sorted with the parameters?
2. Is there a Swagger/OpenAPI doc available?
3. Are you testing with the endpoint that has the most parameters?

These three questions can save you 90% of debugging time.

---

Based on real-world experience from SFD Lab. We spent half a day fighting a DNS management API's signature algorithm before the Swagger doc revealed the answer. Hope this helps fellow developers battling third-party APIs.