RESTful authentication

Before using an Agora RESTful API, you need to setup REST authentication.

Available REST authentication methods are:

• Basic HTTP authentication

  You need to generate a Base64-encoded credential with the Customer ID and Customer Secret provided by Agora and pass the credential to the Authorization parameter in the request header.

Implement authentication on the server; otherwise, you may encounter the risk of data leakage.

To generate a set of Customer ID and Customer Secret, do the following:

1. In Agora Console, click the account name in the top right corner, and click RESTful API from the drop-down list to enter the RESTful API page.

   

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 codes implement basic HTTP authentication and send 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 API

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

}

}

package main

import (

"fmt"

"strings"

"net/http"

"io/ioutil"

"encoding/base64"

)

// HTTP basic authentication example in Golang using the <Vg k="VSDK" /> 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))

}

<?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 request

curl_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;

using System;

using System.IO;

using System.Net;

using System.Text;

// HTTP basic authentication example in C# using the <Vg k="VSDK" /> Server RESTful API

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

}

}

}

// HTTP basic authentication example in node.js using the <Vg k="VSDK" /> Server RESTful API

const https = require('https')

// Customer ID

const customerKey = "Your customer ID"

// Customer secret

const customerSecret = "Your customer secret"

// Concatenate customer key and customer secret and use base64 to encode the concatenated string

const plainCredential = customerKey + ":" + customerSecret

// Encode with base64

encodedCredential = Buffer.from(plainCredential).toString('base64')

authorizationField = "Basic " + encodedCredential

// Set request parameters

const 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 request

const 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()

# -- coding utf-8 --

# Python 3

# HTTP basic authentication example in python using the <Vg k="VSDK" /> Server RESTful API

import base64

import http.client

# Customer ID

customer_key = "Your customer ID"

# Customer secret

customer_secret = "Your customer secret"

# Concatenate customer key and customer secret and use base64 to encode the concatenated string

credentials = customer_key + ":" + customer_secret

# Encode with base64

base64_credentials = base64.b64encode(credentials.encode("utf8"))

credential = base64_credentials.decode("utf8")

# Create connection object with basic URL

conn = http.client.HTTPSConnection("api.agora.io")

payload = ""

# Create Header object

headers = {}

# Add Authorization field

headers['Authorization'] = 'basic ' + credential

headers['Content-Type'] = 'application/json'

# Send request

conn.request("GET", "/dev/v1/projects", payload, headers)

res = conn.getresponse()

data = res.read()

print(data.decode("utf-8"))