RESTful authentication

Media Gateway RESTful API requires REST authentication. The following REST authentication methods are available:

• Basic HTTP authentication

  Generate a Base64-encoded credential with the customer ID and customer secret provided by Agora and pass the credential with the Authorization parameter in the request header.

• HMAC HTTP authentication

  You need to generate a signature through the HMAC-SHA256 algorithm and pass the signature and related information to the Authorization parameter in the request header. This option is recommended since it has a higher security level.

Implement basic HTTP authentication

Generate Customer ID and Customer Secret

To generate a set of customer ID and customer secret, do the following:

1. In Agora Console, click Developer Toolkit > RESTful API.

   

2. Click Add a secret, and click OK. A set of customer ID and customer secret is generated.

3. Click Download in the Customer Secret column. Read the pop-up window carefully, and save the downloaded key_and_secret.txt file in a secure location.

4. Use the customer ID (key) and customer secret (secret) to generate a Base64-encoded credential, and pass the Base64-encoded credential to the Authorization parameter in the HTTP request header.

You can download the customer secret from Agora Console only once. Be sure to keep it secure.

Generate an authorization header using a third-party tool

For testing and debugging, you can use a third-party online tool to quickly generate your Authorization header. Enter your Customer ID as the Username and your Customer Secret as the Password. Your generated header should look like this::

Authorization: Basic NDI1OTQ3N2I4MzYy...YwZjA=a

Basic authentication sample code

The following sample code implements basic HTTP authentication and sends a RESTful API request to get the basic information of all your current Agora projects.

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
  "encoding/base64"
)

// HTTPS basic authentication example in Golang using the RTC SDK Server RESTful API
func main() {

  // Customer ID
  customerKey := "Your customer ID"
  // Customer secret
  customerSecret := "Your customer secret"

  // Concatenate customer key and customer secret and use base64 to encode the concatenated string
  plainCredentials := customerKey + ":" + customerSecret
  base64Credentials := base64.StdEncoding.EncodeToString([]byte(plainCredentials))

  url := "https://api.agora.io/dev/v1/projects"
  method := "GET"

  payload := strings.NewReader(``)

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  // Add Authorization header
  req.Header.Add("Authorization", "Basic " + base64Credentials)
  req.Header.Add("Content-Type", "application/json")

  // Send HTTP request
  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

Implement HMAC HTTP authentication

To implement HMAC HTTP authentication, you need the following information:

• App ID
• Customer ID and customer secret

HMAC authentication sample code

The following sample code demonstrates how to generate the value of the Authorization field:

const crypto = require('crypto');
const http = require('http');

// The app ID of your Agora project
appid = ""
// The customer ID obtained from the RESTful API of the Agora Console
customer_username = ""
// The customer secret obtained from the RESTful API of the Agora Console
customer_secret = ""
// Request package body
data = ""

function hashData(data) {
    const hash = crypto.createHash('sha256');
    hash.update(data);
    return hash.digest('base64');
}
function signData(data) {
    const hmac = crypto.createHmac('sha256', customer_secret);
    hmac.update(data);
    return hmac.digest('base64');
}

date = (new Date()).toUTCString();
reqpath = `/dev/v2/projects/${appid}/rtls/ingress/appconfig`;
reqline = `GET ${reqpath} HTTP/1.1`;
// Calculate the SHA-256 hash
bodySign = hashData(args.data);
digest = `SHA-256=${bodySign}`;
// Generate signature
signingStr = `host: ${host}\ndate: ${date}\n${reqline}\ndigest: ${digest}`;
sign = signData(signingStr);

auth = `hmac username="${customer_username}", `
auth += `algorithm="hmac-sha256", `
auth += `headers="host date request-line digest", `
auth += `signature="${sign}"`;

console.log(`Authorization: ${auth}`);