Tạo chữ ký cho API V2 (Signature)

ClassIn has introduced a new series of APIs to support its upgraded LMS-featured Client. The new LMS APIs will use headers for authentication, no longer relying on the SafeKey parameter.

• The encrypted signature value will be placed in the request header under the parameter “X-EEO-SIGN,” with the encryption rule: sign = md5('request_string&key=secret_key').
• The parameter of sid and timeStamp will be included in the header, instead of the body, corresponding to the parameters “X-EEO-UID” and “X-EEO-TS.” The body requests should no longer include sid and timeStamp.
• The “X-EEO-TS” must be a Unix Epoch timestamp of the current API call within the last 5 minutes, at the second level!
• The body parameters must not use “key” as a parameter name!

Header Example

{
    "X-EEO-SIGN": "5be8ad0ab3740080b8ef240d4e7d6ce4",  // Encrypted parameter sign
    "X-EEO-UID": "1540438",                       // School SID
    "X-EEO-TS": "1726125243",                     // Unix Epoch timestamp within 5 minutes of the current API call
    "Content-Type": "application/json"
}
Copy

How to Generate the Signature

Step 1: Read Parameters from the Request Body

• The body is in JSON format. Extract the key/value pairs for signing based on the following criteria:

  1. Parameters of array and dictionary types do not participate in the signature and should be excluded.
  2. Parameters with a byte length greater than 1024 in the request body are also excluded from the signature.

Step 2: Add Required Parameters, Sort, and Concatenate the String

1. Add sid=XXXXXX and timeStamp=XXXXXXXX to the parameters to be signed.
2. Sort the parameters in ascending order based on their ASCII values (lexicographically), and concatenate them into a string using the URL key-value pair format (i.e., key1=value1&key2=value2…).

Step 3: Concatenate the Secret

Append &key=secret to the end of the string generated in the previous step.

Step 4: Calculate the 32-bit Lowercase MD5 Value

The MD5 hash of the entire string (in 32-bit lowercase) is used as the signature value, referred to as sign.

Step 5: Generate the Header for the API Request

{
    "X-EEO-SIGN": "sign",
    "X-EEO-UID": "sid",
    "X-EEO-TS": "timeStamp", 
    "Content-Type": "application/json"
}
Copy

Example

Here is a sample of the API request, with the secret: Mb7SR6H

curl --location --request POST '/lms/unit/test' \
--header 'X-EEO-SIGN: 4f97f55addf4921a05c2395617cd8a7b' \
--header 'X-EEO-UID: 1000082' \
--header 'X-EEO-TS: 1721095405' \
--header 'Content-Type: application/json' \
--data-raw '{
    "courseId": 132323,
    "unitJson": [
        {
            "name": "string",
            "content": "string",
            "publishFlag": 0
        }
    ],
}'
Copy

1. Concatenate the Request String

   Exclude parameters that do not participate in the signature: unitJson (array). Then, add sid and timeStamp, resulting in the following list of parameters and values:

   | Parameter Name | Parameter Value | |—————-|—————–| | sid | 1000082 | | courseId | 132323 | | timeStamp | 1721095405 |

   Sort the obtained parameters in ascending order based on their ASCII values (lexicographically) and concatenate them into a string using the URL key-value pair format (i.e., key1=value1&key2=value2…), resulting in stringA.

   Finally, append the key (secret) to stringA to obtain the string to be signed.

   Following the above rules, the resulting string to be signed from the example is as follows:

    courseId=132323&sid=1000082&timeStamp=1673949471&key=Mb7SR6H
   Copy

2. Calculate the Signature

   Perform an MD5 hash on the string to be signed to obtain the signature value.

   The computed result for this example is 4f97f55addf4921a05c2395617cd8a7b.

Code Example

Signature Algorithm Code Example

Signature Failure

The error codes related to signature failure are as follows: