RESTful authentication

Before using Media Gateway RESTful API, set up 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.

info

Implement authentication on the server to mitigate the risk of data leakage.

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.

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

Java

import java.io.IOException;import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;import java.util.Base64;// HTTP basic authentication example in Java using the <Vg k="VSDK" /> Server RESTful APIpublic class Base64Encoding {    public static void main(String[] args) throws IOException, InterruptedException {        // Customer ID        final String customerKey = "Your customer ID";        // Customer secret        final String customerSecret = "Your customer secret";        // Concatenate customer key and customer secret and use base64 to encode the concatenated string        String plainCredentials = customerKey + ":" + customerSecret;        String base64Credentials = new String(Base64.getEncoder().encode(plainCredentials.getBytes()));        // Create authorization header        String authorizationHeader = "Basic " + base64Credentials;        HttpClient client = HttpClient.newHttpClient();        // Create HTTP request object        HttpRequest request = HttpRequest.newBuilder()                .uri(URI.create("https://api.agora.io/dev/v1/projects"))                .GET()                .header("Authorization", authorizationHeader)                .header("Content-Type", "application/json")                .build();        // Send HTTP request        HttpResponse<String> response = client.send(request,                HttpResponse.BodyHandlers.ofString());        System.out.println(response.body());    }}

Golang

package mainimport (  "fmt"  "strings"  "net/http"  "io/ioutil"  "encoding/base64")// HTTP basic authentication example in Golang using the <Vg k="VSDK" /> Server RESTful APIfunc 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))}

PHP

<?php// HTTP basic authentication example in PHP using the <Vg k="VSDK" /> Server RESTful API// Customer ID$customerKey = "Your customer ID";// Customer secret$customerSecret = "Your customer secret";// Concatenate customer key and customer secret$credentials = $customerKey . ":" . $customerSecret;// Encode with base64$base64Credentials = base64_encode($credentials);// Create authorization header$arr_header = "Authorization: Basic " . $base64Credentials;$curl = curl_init();// Send HTTP requestcurl_setopt_array($curl, array(  CURLOPT_URL => 'https://api.agora.io/dev/v1/projects',  CURLOPT_RETURNTRANSFER => true,  CURLOPT_ENCODING => '',  CURLOPT_MAXREDIRS => 10,  CURLOPT_TIMEOUT => 0,  CURLOPT_FOLLOWLOCATION => true,  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,  CURLOPT_CUSTOMREQUEST => 'GET',  CURLOPT_HTTPHEADER => array(    $arr_header,    'Content-Type: application/json'  ),));$response = curl_exec($curl);if($response === false) {    echo "Error in cURL : " . curl_error($curl);}curl_close($curl);echo $response;

C#

using System;using System.IO;using System.Net;using System.Text;// HTTP basic authentication example in C# using the <Vg k="VSDK" /> Server RESTful APInamespace Examples.System.Net{    public class WebRequestPostExample    {        public static void Main()        {            // Customer ID            string customerKey = "Your customer ID";            // Customer secret            string customerSecret = "Your customer secret";            // Concatenate customer key and customer secret and use base64 to encode the concatenated string            string plainCredential = customerKey + ":" + customerSecret;            // Encode with base64            var plainTextBytes = Encoding.UTF8.GetBytes(plainCredential);            string encodedCredential = Convert.ToBase64String(plainTextBytes);            // Create authorization header            string authorizationHeader = "Authorization: Basic " + encodedCredential;            // Create request object            WebRequest request = WebRequest.Create("https://api.agora.io/dev/v1/projects");            request.Method = "GET";            // Add authorization header            request.Headers.Add(authorizationHeader);            request.ContentType = "application/json";            WebResponse response = request.GetResponse();            Console.WriteLine(((HttpWebResponse)response).StatusDescription);            using (Stream dataStream = response.GetResponseStream())            {                StreamReader reader = new StreamReader(dataStream);                string responseFromServer = reader.ReadToEnd();                Console.WriteLine(responseFromServer);            }            response.Close();        }    }}

Node.js

// HTTP basic authentication example in node.js using the <Vg k="VSDK" /> Server RESTful APIconst https = require('https')// Customer IDconst customerKey = "Your customer ID"// Customer secretconst customerSecret = "Your customer secret"// Concatenate customer key and customer secret and use base64 to encode the concatenated stringconst plainCredential = customerKey + ":" + customerSecret// Encode with base64encodedCredential = Buffer.from(plainCredential).toString('base64')authorizationField = "Basic " + encodedCredential// Set request parametersconst options = {  hostname: 'api.agora.io',  port: 443,  path: '/dev/v1/projects',  method: 'GET',  headers: {    'Authorization':authorizationField,    'Content-Type': 'application/json'  }}// Create request object and send requestconst req = https.request(options, res => {  console.log(`Status code: ${res.statusCode}`)  res.on('data', d => {    process.stdout.write(d)  })})req.on('error', error => {  console.error(error)})req.end()

Python

# -- coding utf-8 --# Python 3# HTTP basic authentication example in python using the <Vg k="VSDK" /> Server RESTful APIimport base64import http.client# Customer IDcustomer_key = "Your customer ID"# Customer secretcustomer_secret = "Your customer secret"# Concatenate customer key and customer secret and use base64 to encode the concatenated stringcredentials = customer_key + ":" + customer_secret# Encode with base64base64_credentials = base64.b64encode(credentials.encode("utf8"))credential = base64_credentials.decode("utf8")# Create connection object with basic URLconn = http.client.HTTPSConnection("api.agora.io")payload = ""# Create Header objectheaders = {}# Add Authorization fieldheaders['Authorization'] = 'basic ' + credentialheaders['Content-Type'] = 'application/json'# Send requestconn.request("GET", "/dev/v1/projects", payload, headers)res = conn.getresponse()data = res.read()print(data.decode("utf-8"))

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

• App ID
• Customer ID and customer secret

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

_39

const crypto = require('crypto');

_39

const http = require('http');

_39

_39

// The app ID of your Agora project

_39

appid = ""

_39

// The customer ID obtained from the RESTful API of the Agora Console

_39

customer_username = ""

_39

// The customer secret obtained from the RESTful API of the Agora Console

_39

customer_secret = ""

_39

// Request package body

_39

data = ""

_39

_39

function hashData(data) {

_39

const hash = crypto.createHash('sha256');

_39

hash.update(data);

_39

return hash.digest('base64');

_39

}

_39

function signData(data) {

_39

const hmac = crypto.createHmac('sha256', customer_secret);

_39

hmac.update(data);

_39

return hmac.digest('base64');

_39

}

_39

_39

date = (new Date()).toUTCString();

_39

reqpath = `/cn/v1/projects/${appid}/rtls/ingress/appconfig`;

_39

reqline = `GET ${reqpath} HTTP/1.1`;

_39

// Calculate the SHA-256 hash

_39

bodySign = hashData(args.data);

_39

digest = `SHA-256=${bodySign}`;

_39

// Generate signature

_39

signingStr = `host: ${host}\ndate: ${date}\n${reqline}\ndigest: ${digest}`;

_39

sign = signData(signingStr);

_39

_39

auth = `hmac username="${customer_username}", `

_39

auth += `algorithm="hmac-sha256", `

_39

auth += `headers="host date request-line digest", `

_39

auth += `signature="${sign}"`;

_39

_39

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