Help Center/ KooDrive/ API Reference/ Appendixes/ App-based Authentication Generation Rule/ Step 1: Construct a Standard Request (CanonicalRequest)
Updated on 2025-10-16 GMT+08:00
View PDF
Share

Step 1: Construct a Standard Request (CanonicalRequest)

To use AppId/AppSecret for signature and authentication, create a standard request, and then sign the request. The third party and KooDrive use the same request specifications to ensure that the frontend and backend of the same HTTP request obtain the same signature result for identity verification.

CanonicalRequest =
HTTPRequestMethod + '\n' +    //HTTP request method, all in uppercase letters
  CanonicalURI + '\n' +         //Canonical URI
  CanonicalQueryString + '\n' + //Canonical query string
  CanonicalHeaders + '\n' +     //Canonical message header
  SignedHeaders + '\n' +        //Signed header
  HashedRequestPayload

Constructing an HTTP Request Method (HTTPRequestMethod)

HTTP request methods, such as GET, PUT, and POST, end with a newline character.

Add a Standard URI Parameter (CanonicalURI)

Definition:

Path of the requested resource, which is the URI code of the absolute path.

Format:

Standard URI path based on RFC 3986.

  • The redundant and relative paths are removed.
  • Each part of the path must be URI-encoded.
  • If the URI does not end with a slash (/), add a slash at the end.

Adding a Standard Query String (CanonicalQueryString)

Definition:

Query string. If no query string is configured, an empty string is used.

Format:

Pay attention to the following to ensure standard query strings:

  • Do not perform URI encoding on any non-reserved characters defined in RFC 3986, including A–Z, a–z, 0–9, hyphen (-), underscore (_), period (.), and tilde (~).
  • Use %XY to perform percent encoding on all non-reserved characters. X and Y indicate hexadecimal characters (0–9 and A–F). For example, the space character must be encoded as %20, and an extended UTF-8 character must be encoded in the "%XY%ZA%BC" format.
  • Add "URI-encoded parameter name=URI-encoded parameter value" to each parameter. If no value is specified, use an empty string instead. The equal sign (=) is required. For example, in the following string that contains two parameters, the value of parameter parm2 is empty.

    parm1=value1&parm2=

  • Sort the parameters in alphabetically ascending order. For example, a parameter starting with uppercase letter F precedes another parameter starting with lowercase letter b.
  • Construct a standard query string from the first parameter after sorting.

Adding a Standard Message Header (CanonicalHeaders)

Definition:

List of standard request headers, including all HTTP message headers in the to-be-signed request. The message header must contain X-Date and X-User-Id.

Format:

CanonicalHeaders consists of multiple message headers, for example, CanonicalHeadersEntry0 + CanonicalHeadersEntry1 + .... Each message header (CanonicalHeadersEntry) is in the format of Lowercase(HeaderName) + ':' + Trim(HeaderValue) + '\n'.

Description:

  • Lowercase(String): a function for converting all letters into lowercase letters.
  • Trim(String): a function for deleting the spaces before and after a value.
  • The last message header carries a newline character. Therefore, an empty line appears because the CanonicalHeaders field also contains a CRLF according to the specifications.
  • The message header name must be unique. Otherwise, authentication fails.

Adding a Message Header (SignedHeaders) for Request Signing

Definition:

List of message headers used for request signing. This header is used to notify KooDrive of the request headers that are part of the signing process. X-Date and X-User-Id must be used as signed headers.

Format:

SignedHeaders = Lowercase(HeaderName0) + ';' + Lowercase(HeaderName1) + ";" + ...

Letters in the message headers are converted to lowercase letters. All headers are sorted alphabetically and separated with semicolons (;).

Description:

Lowercase(String): a function for converting all letters into lowercase letters.

Calculating and Adding the Hash Value (HashRequestPayload) Based on the Request Body

Definition:

Generate a hash value using the message body of the request.

The pseudocode is as follows:

HashRequestPayload = HexEncode(Hash(RequestPayload))

Description:

  • Hash(String): a function for generating a message digest. Currently, SHA-256 is supported.
  • HexEncode(String): Base16 encoding function for returning a digest consisting of lowercase letters. Each byte you enter is expressed as two hexadecimal characters.