Accessing Server APIs

Request structure

Service URL format

Developers need to specify the corresponding access address based on the geographical region of their server when sending requests to the ZEGOCLOUD server.

ZEGOCLOUD supports request access from the following geographical regions:

The ${PRODUCT} part in the URLs represents the ZEGO product:

Communication protocol

For secure communications, all the Server APIs must be accessed via HTTPS requests.

Request method

The Server APIs support the following HTTP request methods:

• GET
• POST

Public parameters

Public request parameters

Public request parameters are the parameters that are required for every API request.

Sample request:

https://${PRODUCT}-api.zego.im/?Action=xxx
&AppId=1234567890
&SignatureNonce=15215528852396
&Timestamp=1234567890
&Signature=Pc5WB8gokVn0xfeu%2FZV%2BiNM1dgI%3D
&SignatureVersion=2.0
&IsTest=false
&<Non-public Request Parameters>

https://${PRODUCT}-api.zego.im/?Action=xxx
&AppId=1234567890
&SignatureNonce=15215528852396
&Timestamp=1234567890
&Signature=Pc5WB8gokVn0xfeu%2FZV%2BiNM1dgI%3D
&SignatureVersion=2.0
&IsTest=false
&<Non-public Request Parameters>

Public response parameters

All responses to API requests are returned in a unified format, with the returned data in JSON format.

The following public response parameters will be included in the response to every request, regardless of whether the request is successful.

Sample response:

{
    "Code":0,
    "Data":{
        "MessageId":"1_1611647493487_29"
    },
    "Message":"success",
    "RequestId":"2237080460466033406"
}

{
    "Code":0,
    "Data":{
        "MessageId":"1_1611647493487_29"
    },
    "Message":"success",
    "RequestId":"2237080460466033406"
}

Signing the requests

To ensure secure API calls, the ZEGO server authenticates every API request, which means a request signature must be included in every API request.

Get the AppId and Server Secret Key

To generate a request signature, you will need to use the AppId and ServerSecret assigned to your project by ZEGO. The AppId is used as the identifier of the request sender, and ServerSecret is the secret key to generate the signature string on the request sender side and verify the signature on the ZEGO server. To ensure system security, please keep this information strictly confidential.

You can find the AppId and ServerSecret of your project in the ZEGOCLOUD Admin Console.

Generate a signature

1. Parameters required to generate a signature

2. Signature algorithm

Signature = md5(AppId + SignatureNonce + ServerSecret + Timestamp)

3. Format of the Signature string

The Signature is a hex string of 32 characters in lower case.

Signature sample code

ZEGO provides sample code in various programming languages for generating the signature.

import (
   "crypto/md5"
   "crypto/rand"
   "encoding/hex"
   "fmt"
   "log"
   "time"
)
// Signature=md5(AppId + SignatureNonce + ServerSecret + Timestamp)
func GenerateSignature(appId uint32, signatureNonce string, serverSecret string, timestamp int64) (Signature string){
   data := fmt.Sprintf("%d%s%s%d", appId, signatureNonce, serverSecret, timestamp)
   h := md5.New()
   h.Write([]byte(data))
   return hex.EncodeToString(h.Sum(nil))
}
func main() {
  /*Generate a random hex string of 16 hex digits*/
   nonceByte := make([]byte, 8)
   rand.Read(nonceByte)
   signatureNonce := hex.EncodeToString(nonceByte)
   log.Printf(signatureNonce)
   appId := 12345       //Use the AppID and ServerSecret of your project.
   serverSecret := "9193cc662a4c0ec135ec71fb57194b38"
   timestamp := time.Now().Unix()
   /* appId:12345
      signatureNonce:4fd24687296dd9f3
      serverSecret:9193cc662a4c0ec135ec71fb57194b38
      timestamp:1615186943      2021/03/08 15:02:23
      signature:43e5cfcca828314675f91b001390566a
    */
   log.Printf("signature:%v", GenerateSignature(uint32(appId), signatureNonce, serverSecret, timestamp))
}

import (
   "crypto/md5"
   "crypto/rand"
   "encoding/hex"
   "fmt"
   "log"
   "time"
)
// Signature=md5(AppId + SignatureNonce + ServerSecret + Timestamp)
func GenerateSignature(appId uint32, signatureNonce string, serverSecret string, timestamp int64) (Signature string){
   data := fmt.Sprintf("%d%s%s%d", appId, signatureNonce, serverSecret, timestamp)
   h := md5.New()
   h.Write([]byte(data))
   return hex.EncodeToString(h.Sum(nil))
}
func main() {
  /*Generate a random hex string of 16 hex digits*/
   nonceByte := make([]byte, 8)
   rand.Read(nonceByte)
   signatureNonce := hex.EncodeToString(nonceByte)
   log.Printf(signatureNonce)
   appId := 12345       //Use the AppID and ServerSecret of your project.
   serverSecret := "9193cc662a4c0ec135ec71fb57194b38"
   timestamp := time.Now().Unix()
   /* appId:12345
      signatureNonce:4fd24687296dd9f3
      serverSecret:9193cc662a4c0ec135ec71fb57194b38
      timestamp:1615186943      2021/03/08 15:02:23
      signature:43e5cfcca828314675f91b001390566a
    */
   log.Printf("signature:%v", GenerateSignature(uint32(appId), signatureNonce, serverSecret, timestamp))
}

Signature failures

When a signature verification fails, an error code will be returned.