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.

• AccessToken2

  You need to fill the Authorization: agora token= field with the Signaling SDK AccessToken2 generated from your server.

• AccessToken

  You need to fill the x-agora-token and x-agora-uid fields in the request header with the following information:

  • The Signaling SDK AccessToken generated from your server
  • The Signaling SDK user ID used to generate the Signaling token

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

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"))

1. Generate the token for your app.

2. Enter the Signaling token and the Signaling user ID into the x-agora-token and x-agora-uid fields of the HTTP request header, respectively.

The following sample codes implement AccessToken2 authentication and send a request with the Signaling RESTful API to get Signaling user events.

import java.io.IOException;

import java.net.URI;

import java.net.http.HttpClient;

import java.net.http.HttpRequest;

import java.net.http.HttpResponse;

// Token authentication example in Java using the Signaling user events RESTful API

class TokenAuthExample {

public static void main(String[] args) throws IOException, InterruptedException {

// Signaling token

final String tokenValue = "input your token value here";

// App ID

final String appID = "input your app ID here";

String urlStr = String.format("https://api.agora.io/dev/v2/project/%s/rtm/vendor/user_events", appID);

String authValue = String.format("agora token=%s", tokenValue);

// Create request object

HttpRequest request = HttpRequest.newBuilder()

.uri(URI.create(urlStr))

.GET()

.header("Authorization", authValue)

.header("Content-Type", "application/json")

.build();

// Send request

HttpClient client = HttpClient.newHttpClient();

HttpResponse<String> response = client.send(request,

HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());

}

}

package main

import (

"fmt"

"io/ioutil"

"net/http"

)

func main() {

if err := tokenAuthExamle(); err != nil {

panic(err)

}

}

// Token authentication example in Golang using the Signaling user events RESTful API

func tokenAuthExamle() error {

var (

// Signaling Token

tokenValue = "input the token value here"

// App ID

appID = "input your app ID here"

urlstr = fmt.Sprintf("https://api.agora.io/dev/v2/project/%s/rtm/vendor/user_events", appID)

authValue = fmt.Sprintf("agora token=%s", tokenValue)

)

// Create request object

req, err := http.NewRequest(http.MethodGet, urlstr, nil)

if err != nil {

return fmt.Errorf("failed to new http request, %w", err)

}

// Set Authorization header

req.Header.Set("Authorization", authValue)

req.Header.Set("Content-Type", "application/json")

// Send request

resp, err := http.DefaultClient.Do(req)

if err != nil {

return fmt.Errorf("failed to send request, %w", err)

}

defer resp.Body.Close()

// Read response body

body, err := ioutil.ReadAll(resp.Body)

if err != nil {

return fmt.Errorf("failed to read response body, %w", err)

}

// Respond status code

if resp.StatusCode/100 != 2 {

return fmt.Errorf("StatusCode(%d) != 2xx, %s", resp.StatusCode, string(body))

}

// Print response body

fmt.Println(string(body))

return nil

}

// Token authentication example in node.js using the Signaling user events RESTful API

const https = require('https')

// Signaling Token

var token_value = "input your token here"

// App ID

var app_id = "input your app ID"

var url_path = `/dev/v2/project/${app_id}/rtm/vendor/user_events`

var auth_token = `agora token=${token_value}`

// Set request parameters

const options = {

hostname: 'api.agora.io',

port: 443,

path: url_path,

method: 'GET',

headers: {

// Add the authorization field to the header

'Authorization': auth_token,

'Content-Type': 'application/json'

}

}

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

import http.client

# Token authentication example in Python using the Signaling user events RESTful API

# Signaling Token

token_value = "input your token here"

# App ID

app_id = "input your app ID here"

url_path = "/dev/v2/project/{0}/rtm/vendor/user_events".format(app_id)

auth_value = "agora token={0}".format(token_value)

# Create connection object with base URL

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

# Create header

headers = {}

# Add authorization header

headers['Authorization'] = auth_value

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

payload = ""

# Send request

conn.request("GET", url_path, payload, headers)

res = conn.getresponse()

data = res.read()

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

The following sample codes implement AccessToken authentication and send a request with the Signaling RESTful API to get Signaling user events.

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;

// Token authentication example in Java using the Signaling user events RESTful API

public class Base64Encoding {

public static void main(String[] args) throws IOException, InterruptedException {

// Signaling Token

String token = "Your Signaling token";

// User ID used to generate the Signaling token

String uid = "test_user";

HttpClient client = HttpClient.newHttpClient();

// Create request object

HttpRequest request = HttpRequest.newBuilder()

.uri(URI.create("https://api.agora.io/dev/v2/project/<Your App ID>/rtm/vendor/user_events"))

.GET()

// Add the x-agora-token field to the header

.header("x-agora-token", token )

// Add the x-agora-uid field to the header

.header("x-agora-uid", uid)

.header("Content-Type", "application/json")

.build();

// Send request

HttpResponse<String> response = client.send(request,

HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());

}

}

package main

import (

"fmt"

"strings"

"net/http"

"io/ioutil"

)

// Token authentication example in Golang using the Signaling user events RESTful API

func main() {

// Signaling Token

token := "Your Signaling Token"

// User ID used to generate the Signaling token

uid := "test_user"

url := "https://api.agora.io/dev/v2/project/<Your App ID>/rtm/vendor/user_events"

method := "GET"

payload := strings.NewReader(``)

client := &http.Client {

}

req, err := http.NewRequest(method, url, payload)

if err != nil {

fmt.Println(err)

return

}

// Add the x-agora-token field to the header

req.Header.Add("x-agora-token", token)

// Add the x-agora-uid field to the header

req.Header.Add("x-agora-uid", uid)

req.Header.Add("Content-Type", "application/json")

// Send 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

// Token authentication example in PHP using the Signaling user events RESTful API

// Signaling Token

$token = "Your Signaling Token";

// User ID used to generate the Signaling token

$uid = "test_user";

// Add the x-agora-token field to the header

$token_header = "x-agora-token: " . $token;

// Add the x-agora-uid field to the header

$uid_header = "x-agora-uid: " . $uid;

$curl = curl_init();

// Send request

curl_setopt_array($curl, array(

CURLOPT_URL => 'https://api.agora.io/dev/v2/project/<Your App ID>/rtm/vendor/user_events',

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(

$token_header,

$uid_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;

// Token authentication example in C# using the Signaling user events RESTful API

namespace Examples.System.Net

{

public class WebRequestPostExample

{

public static void Main()

{

// Signaling Token

string token = "Your Signaling Token";

// User ID used to generate the Signaling token

string uid = "userA";

// Add the x-agora-token field to the header

string tokenHeader = "x-agora-token: " + token;

// Add the x-agora-uid field to the header

string uidHeader = "x-agora-uid: " + uid;

WebRequest request = WebRequest.Create("https://api.agora.io/dev/v2/project/<Your App ID>/rtm/vendor/user_events");

request.Method = "GET";

// Add header to the request

request.Headers.Add(tokenHeader);

request.Headers.Add(uidHeader);

request.ContentType = "application/json";

// Get response

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

}

}

}

// Token authentication example in node.js using the Signaling user events RESTful API

const https = require('https')

// Signaling Token

token = "Your Signaling Token"

// User ID used to generate the Signaling token

uid = "test_user"

// Set request parameters

const options = {

hostname: 'api.agora.io',

port: 443,

path: '/dev/v2/project/<Your App ID>/rtm/vendor/user_events',

method: 'GET',

headers: {

// Add the x-agora-token field to the header

'x-agora-token':token,

// Add the x-agora-uid field to the header

'x-agora-uid': uid,

'Content-Type': 'application/json'

}

}

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

import http.client

# Token authentication example in Python using the Signaling user events RESTful API

# Create connection object with base URL

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

# Create header

headers = {}

# Add the x-agora-token field to the header

headers['x-agora-token'] = "Your Signaling Token"

# Add the x-agora-uid field to the header, which is the user ID used to generate the Signaling token

headers['x-agora-uid'] = "test_user"

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

payload = ""

# Send request

conn.request("GET", "/dev/v2/project/<Your App ID>/rtm/vendor/user_events", payload, headers)

res = conn.getresponse()

data = res.read()

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