Skip to main content
  • Core Products
  • Add-Ons
  • Extensions Marketplace
Android
iOS
Web
Windows
Unity
Flutter
React Native

Secure authentication with tokens

Agora uses digital tokens to authenticate users and their privileges before they access Agora Chat. For test purposes, you can generate temporary tokens in Agora Console. See Manage users and generate tokens for details.

In a development environment, you deploy your own app server to generate authentication tokens. This page introduces how to set up a token server, retrieve tokens from your server, and authenticate your users.

Understand the tech​

Agora Chat employs two types of tokens for authentication:

  • Use tokens with app privileges to call Agora RESTful APIs.

  • Use tokens with user privileges for user authentication and interaction through the Agora Chat SDK.

Use-caseToken typeInformation required to generateMaximum validity
RESTful API callsToken with app privileges
  • App ID of your Agora Chat project
  • App certificate of your Agora Chat project
  • Token validity period for your Agora Chat project
24 hours
SDK API callsToken with user privileges
  • App ID of your Agora Chat project
  • App certificate of your Agora Chat project
  • Token validity period for your Agora Chat project
  • The Agora Chat user ID
24 hours

Prerequisites​

In order to follow this procedure, you must have the following:

If you have a firewall implemented in your network environment, Agora provides a firewall whitelist solution for you to access Agora Chat in environments with restricted network access. If you want to use the firewall whitelist solution, submit a ticket and our technical support will provide the target domain and corresponding IP.

Implement the authentication flow​

This section shows you how to supply and consume a token used to authenticate a user with Agora Chat.

Deploy an app server to generate tokens​

Tokens used for connecting with Agora Chat are generated by your app server. When a client sends a request, the app server generates an appropriate token. The following figure shows how to manage tokens with app and user privileges to facilitate secure user authentication and interaction with Agora Chat services.

Token generation API call sequence

token_generate_user_token

This section guides you through setting up a token server. Choose your preferred language and follow the step-by-step procedure.

caution

This sample server code provided in this guide is for demonstration purposes only. Do not use it directly in a production environment.

  1. Create and initialize a Go project

    Open your terminal and execute the following commands:

    mkdir chat-token-server
    cd chat-token-server
    go mod init chat-token-server

  2. Add the Agora Tools dependency

    The code uses the chatTokenBuilder library to generate tokens with app and user privileges.

    go get github.com/AgoraIO/Tools/DynamicKey/AgoraDynamicKey/go/src/chatTokenBuilder

  3. Set up the Go HTTP server

    Create a new file server.go, with the following content:

    package mainimport (    "encoding/json"    "fmt"    "log"    "net/http"    "github.com/AgoraIO/Tools/DynamicKey/AgoraDynamicKey/go/src/chatTokenBuilder" )// App credentialsconst (    AppID          = "your_app_id"          // Replace with your actual App ID    AppCertificate = "your_app_certificate" // Replace with your actual App Certificate)type TokenRequest struct {    UserUUID string `json:"user_uuid,omitempty"` // Optional for App Token    Expire   uint32 `json:"expire"`}type TokenResponse struct {    Token string `json:"token"`    Error string `json:"error,omitempty"`}func buildUserTokenHandler(w http.ResponseWriter, r *http.Request) {    var req TokenRequest    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {        http.Error(w, "Invalid request payload", http.StatusBadRequest)        return    }    token, err := chatTokenBuilder.BuildChatUserToken(AppID, AppCertificate, req.UserUUID, req.Expire)    if err != nil {        response := TokenResponse{Error: err.Error()}        json.NewEncoder(w).Encode(response)        return    }    response := TokenResponse{Token: token}    json.NewEncoder(w).Encode(response)}func buildAppTokenHandler(w http.ResponseWriter, r *http.Request) {    var req TokenRequest    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {        http.Error(w, "Invalid request payload", http.StatusBadRequest)        return    }    token, err := chatTokenBuilder.BuildChatAppToken(AppID, AppCertificate, req.Expire)    if err != nil {        response := TokenResponse{Error: err.Error()}        json.NewEncoder(w).Encode(response)        return    }    response := TokenResponse{Token: token}    json.NewEncoder(w).Encode(response)}func main() {    http.HandleFunc("/generate-user-token", buildUserTokenHandler)    http.HandleFunc("/generate-app-token", buildAppTokenHandler)    port := "8080"    fmt.Printf("Starting server on port %s...\n", port)    if err := http.ListenAndServe(":"+port, nil); err != nil {        log.Fatalf("Server failed to start: %v", err)    } }

  4. Run the server

    In server.go, update the values for AppIDd and AppCertificate. Use the following command to run the server:

    go run server.go

    The server will start on http://localhost:8080.

  5. Test the server

    Use the following curl requests to test your server:

    • Generate a user token

      curl -X POST http://localhost:8080/generate-user-token \
            -H "Content-Type: application/json" \
            -d '{"user_uuid": "test_user", "expire": 3600}'

    • Generate an app token

      curl -X POST http://localhost:8080/generate-app-token \
            -H "Content-Type: application/json" \
            -d '{"expire": 3600}'

Chat SDK token authentication​

The following code fetches and replaces an expired token for the Agora Chat SDK. It performs the following tasks:

  1. Fetches a fresh token on app startup* At the start of the application, it fetches a valid token for the user from a token server.
  1. Listens for onTokenWillExpire event: The app sets up a listener to monitor when the token is about to expire. Upon receiving this event, it fetches a new token from the token server and renews the token with the Agora Chat SDK.

To execute the code, ensure you set the following values in the code:

  • App Key: The app key of your Agora project.
  • User ID: The username that you will be used communication.
  • Token Server URL: The URL of your token server, which provides valid tokens for authentication.
import 'package:flutter/material.dart';
import 'package:agora_chat_sdk/agora_chat_sdk.dart';
import 'package:http/http.dart' as http; // Add this for HTTP requests
import 'dart:convert';

class MyHomePage extends StatefulWidget {
@override
_MyHomePageState createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
final String appKey = "YOUR_APP_KEY";
final String tokenServerUrl = "YOUR_TOKEN_SERVER_URL"; // Replace with your server URL
String userId = "YOUR_USER_ID";
String token = "";
bool isJoined = false;

late ChatClient agoraChatClient;

@override
void initState() {
super.initState();
setupChatClient();
setupListeners();
}

/// Initializes the Agora Chat SDK client.
void setupChatClient() async {
ChatOptions options = ChatOptions(
appKey: appKey,
autoLogin: false,
);
agoraChatClient = ChatClient.getInstance;
await agoraChatClient.init(options);

// Notify the SDK that the UI is ready.
await ChatClient.getInstance.startCallback();
}

/// Sets up event listeners for the chat client.
void setupListeners() {
agoraChatClient.addConnectionEventHandler(
"CONNECTION_HANDLER",
ConnectionEventHandler(
onTokenWillExpire: onTokenWillExpire,
onTokenDidExpire: onTokenDidExpire,
),
);
}

/// Fetches a new token from the server.
Future<void> fetchToken() async {
try {
final response = await http.post(
Uri.parse(tokenServerUrl),
headers: {'Content-Type': 'application/json'},
body: jsonEncode({"userId": userId}),
);

if (response.statusCode == 200) {
final data = jsonDecode(response.body);
setState(() {
token = data["token"];
});
showLog("Token fetched successfully");
} else {
showLog("Failed to fetch token: ${response.statusCode}");
}
} catch (e) {
showLog("Error fetching token: $e");
}
}

/// Callback for token expiration warning.
void onTokenWillExpire() async {
showLog("Token will expire soon. Fetching a new token...");
await fetchToken();
// Renew the token
await agoraChatClient.renewToken(token);
showLog("Token renewed successfully");
}

/// Callback for token expiration.
void onTokenDidExpire() async {
showLog("Token expired. Fetching a new token...");
await fetchToken();
// Re-login with the new token
try {
await agoraChatClient.loginWithAgoraToken(userId, token);
showLog("Re-logged in successfully with the new token");
} catch (e) {
showLog("Failed to re-login: $e");
}
}

/// Handles user join or leave (login/logout).
void joinLeave() async {
if (!isJoined) {
// Log in
try {
if (token.isEmpty) {
await fetchToken(); // Fetch token before logging in
}
await agoraChatClient.loginWithAgoraToken(userId, token);
showLog("Logged in successfully as $userId");
setState(() {
isJoined = true;
});
} on ChatError catch (e) {
if (e.code == 200) {
// Already logged in
setState(() {
isJoined = true;
});
} else {
showLog("Login failed, code: ${e.code}, desc: ${e.description}");
}
}
} else {
// Log out
try {
await agoraChatClient.logout(true);
showLog("Logged out successfully");
setState(() {
isJoined = false;
});
} on ChatError catch (e) {
showLog("Logout failed, code: ${e.code}, desc: ${e.description}");
}
}
}

@override
void dispose() {
agoraChatClient.chatManager.removeEventHandler("MESSAGE_HANDLER");
agoraChatClient.removeConnectionEventHandler("CONNECTION_HANDLER");
super.dispose();
}

/// Utility method to log messages in the app.
void showLog(String message) {
// You can implement a logging mechanism, such as a SnackBar or debug console log.
debugPrint(message);
}

@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(
title: Text("Agora Chat Example"),
),
body: Padding(
padding: const EdgeInsets.all(16.0),
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: [
ElevatedButton(
onPressed: joinLeave,
child: Text(isJoined ? "Leave" : "Join"),
),
],
),
),
);
}
}
Copy

Chat RESTful API token authentication​

To create a new user, use the following curl command:

curl -X POST -H "Authorization: Bearer <YourAgoraAppToken>" -i "https://XXXX/XXXX/XXXX/users" -d '[
{
"username": "user1",
"password": "123",
"nickname": "testuser"
}
]'
Copy

The server responds with the user details:

{
"action": "post",
"application": "8be024f0-e978-11e8-b697-5d598d5f8402",
"path": "/users",
"entities": [
{
"uuid": "0ffe2d80-ed76-11e8-8d66-279e3e1c214b",
"username": "user1",
"activated": true,
"nickname": "testuser"
}
]
}
Copy

Reference​

This section introduces token generator libraries, version requirements, and related documents about tokens.

Token generator libraries​

For more examples and source code in other development languages, explore the AgoraDynamicKey open-source repository on GitHub.

Tokens for Agora RTC products​

If you use Agora Chat together with the Agora RTC SDK, Agora recommends upgrading to AccessToken 2.

Page Content

vundefined