API Request Signature

To access the IM Service Server API, you need to sign the API requests to allow the IM Service to verify the identity of your application.

The basic process is as follows:

1. App Backend needs to pre-configure the App Key and App Secret in the authentication service.
2. When calling the Server API, you need to meet the HTTP Header requirements. The signature in the HTTP Header must be calculated using the App Secret, a random number, and a timestamp.
3. Upon receiving the request, the IM Service will perform the same calculation using the corresponding App Secret and require the results to match exactly.
4. Note that the App Secret must not be leaked. Do not transmit the App Secret over the network or store it in untrusted locations (e.g., browsers).

Obtain App Key / App Secret

Obtaining the App Key / App Secret is a prerequisite for using the IM Service Server API. You can visit the App Key page in the Console to query this information.

You need to record the App Key and App Secret of your application as shown in the image above, and use them in this tutorial. When requesting the IM Service Server API, each HTTP request must carry the App Key and the data signature. The App Secret is used to calculate the data signature, so please ensure it is not disclosed.

HTTP Header

When the App Server calls the API, each HTTP request must carry the following HTTP Header fields to provide authentication information to the IM Service:

Default Name	With RC- Prefix	Type	Description
App-Key	RC-App-Key	String	The App Key assigned by the Console.
Nonce	RC-Nonce	String	A random number, no more than 18 characters.
Timestamp	RC-Timestamp	String	The timestamp, in milliseconds, starting from 00:00:00 on January 1, 1970.
Signature	RC-Signature	String	The data signature. You need to generate this field's value by referring to the Signature Calculation Method below.

(Optional) Add the X-Request-ID Field to the Header

We recommend including the X-Request-ID field in the Server API headers sent to RC, as it helps RC troubleshoot issues more efficiently. RC's Server SDK automatically includes the X-Request-ID field, so you do not need to generate it separately.

Server SDK Links:

• server-sdk-java (GitHub)
• server-sdk-php (GitHub)
• server-sdk-go (GitHub)

If you need to generate the X-Request-ID yourself (maximum length of 36 characters), you can refer to the following examples:

Java Example:

import java.util.UUID;

HttpURLConnection conn = getHttpURLConnection(config, uri);
conn.setRequestProperty("X-Request-ID", UUID.randomUUID().toString().replaceAll("\\-", ""));

PHP Example:

private function create_guid()
{
    $charid = strtoupper(md5(uniqid(mt_rand(), true)));
    $uuid = substr($charid, 0, 8)
        . substr($charid, 8, 4)
        . substr($charid, 12, 4)
        . substr($charid, 16, 4)
        . substr($charid, 20, 12);
    return strtolower($uuid);
}
$header = [
    'RC-App-Key:' . $appKey,
    'RC-Nonce:' . $nonce,
    'RC-Timestamp:' . $timeStamp,
    'RC-Signature:' . $sign,
    'X-Request-ID:' . $this->create_guid()
];

Go Example:

import  "github.com/google/uuid"
// getSignature generates the signature locally
// The Signature (data signature) is calculated by concatenating the App Secret, Nonce (random number),
// and Timestamp (timestamp) in order and performing SHA1 hashing. If the data signature verification fails, the API call will return HTTP status code 401.
func (rc RC) getSignature() (nonce, timestamp, signature string) {
	nonceInt := rand.Int()
	nonce = strconv.Itoa(nonceInt)
	timeInt64 := time.Now().Unix()
	timestamp = strconv.FormatInt(timeInt64, 10)
	h := sha1.New()
	_, _ = io.WriteString(h, rc.appSecret+nonce+timestamp)
	signature = fmt.Sprintf("%x", h.Sum(nil))
	return
}

// fillHeader adds API signature to the Http Header
func (rc RC) fillHeader(req *httplib.BeegoHTTPRequest) string {
	requestId := uuid.New().String()
	nonce, timestamp, signature := rc.getSignature()
	req.Header("RC-App-Key", rc.appKey)
	req.Header("RC-Timestamp", timestamp)
	req.Header("RC-Nonce", nonce)
	req.Header("RC-Signature", signature)
	req.Header("Content-Type", "application/json")
	req.Header("User-Agent", USERAGENT)
	req.Header("RC-Request-Id", requestId)
	return requestId
}

Note Each request should carry a newly generated X-Request-ID. If you do not generate it yourself, the RC server will generate an X-Request-ID for the request and return it in the response Header.

Signature Calculation Method

The API request must carry the data signature (Signature) field, which needs to be calculated by the App Backend. The steps are as follows:

1. Log in to the Console and obtain the App Secret corresponding to your App Key.

2. Concatenate the following three strings in order (App Secret + Nonce + Timestamp) and perform SHA1 hashing.

   • App Secret: The App Secret corresponding to your App Key.
   • Nonce: A random number.
   • Timestamp: The timestamp.

The IM Service will verify the authenticity of the data signature before executing the requested action. If the data signature verification fails, the API call will return HTTP status code 401. For other status codes, please refer to the Status Code Table.

Below is a PHP code example for calculating the data signature:

// Reset the random number seed.
srand((double)microtime()*1000000);

$appSecret = 'your-own-app-secret'; // Replace with the App Secret obtained from the developer platform.
$nonce = rand(); // Get a random number.
$timestamp = time()*1000; // Get the timestamp (in milliseconds).

$signature = sha1($appSecret.$nonce.$timestamp);

HTTP Request Example

The following HTTP request example demonstrates the HTTP Header fields in an API request.

POST /user/getToken.json HTTP/1.1
Host: api.rong-api.com
App-Key: your-own-app-key
Nonce: 14314
Timestamp: 1408710653000
Signature: 30be0bbca9c9b2e27578701e9fda2358a814c88f
Content-Type: application/x-www-form-urlencoded
Content-Length: 78

userId=jlk456j5&name=Ironman&portraitUri=http%3A%2F%2Fabc.com%2Fmyportrait.jpg