Skip to main content

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.

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.

    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.

Basic authentication sample code

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.

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());    }}

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:


_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}`);

vundefined