Agora Token Generator for Dart/Flutter #

A powerful and lightweight Flutter package for generating Agora Dynamic Keys and Access Tokens for use with Agora.io SDKs. This package provides a pure Dart implementation of Agora's token generation mechanism with zero native dependencies.

🌐 Live Demo

🚀 Features #

✅ RTC Token Generation - For Agora Real-Time Communications (Video/Audio calls)
✅ RTM Token Generation - For Agora Real-Time Messaging
✅ Multi-Service Tokens - Combined tokens for both RTC and RTM services
✅ Latest Token Format - Supports AccessToken2 (007) format
✅ Zero Native Dependencies - Pure Dart implementation
✅ Flutter Web Support - Works seamlessly on all Flutter platforms
✅ Type Safety - Full Dart type safety with comprehensive documentation
✅ Production Ready - Used in real-world applications

📦 Installation #

Add this package to your pubspec.yaml file:

dependencies:
  agora_token_generator: ^0.0.1

Then install it:

flutter pub get

🏃‍♂️ Quick Start #

Basic RTC Token (Video Calling) #

import 'package:agora_token_generator/agora_token_generator.dart';

void main() {
  // Your Agora project credentials
  const String appId = 'YOUR_APP_ID';
  const String appCertificate = 'YOUR_APP_CERTIFICATE';
  const String channelName = 'my_video_call';
  const int uid = 12345;
  const int tokenExpireSeconds = 3600; // 1 hour

  // Generate RTC token
  String token = RtcTokenBuilder.buildTokenWithUid(
    appId: appId,
    appCertificate: appCertificate,
    channelName: channelName,
    uid: uid,
    tokenExpireSeconds: tokenExpireSeconds,
  );

  print('🎯 RTC Token: $token');
}

RTM Token (Messaging) #

import 'package:agora_token_generator/agora_token_generator.dart';

void main() {
  const String appId = 'YOUR_APP_ID';
  const String appCertificate = 'YOUR_APP_CERTIFICATE';
  const String userId = 'user_123';
  const int tokenExpireSeconds = 3600;

  String token = RtmTokenBuilder.buildToken(
    appId: appId,
    appCertificate: appCertificate,
    userId: userId,
    tokenExpireSeconds: tokenExpireSeconds,
  );

  print('💬 RTM Token: $token');
}

📚 Comprehensive Usage Guide #

1. RTC Tokens for Video/Audio Calling #

Token with Numeric User ID

Perfect for scenarios where you use numeric user identifiers:

String rtcToken = RtcTokenBuilder.buildTokenWithUid(
  appId: 'your_app_id',
  appCertificate: 'your_app_certificate',
  channelName: 'gaming_room_1',
  uid: 12345,
  tokenExpireSeconds: 7200, // 2 hours
);

Token with String User Account

Ideal when using string-based user accounts:

String rtcToken = RtcTokenBuilder.buildTokenWithAccount(
  appId: 'your_app_id',
  appCertificate: 'your_app_certificate',
  channelName: 'meeting_room_abc',
  account: 'john.doe@example.com',
  tokenExpireSeconds: 3600,
);

Token with UID = 0 (Wildcard)

Useful for guest users or when UID is assigned dynamically:

String rtcToken = RtcTokenBuilder.buildTokenWithUid(
  appId: 'your_app_id',
  appCertificate: 'your_app_certificate',
  channelName: 'public_broadcast',
  uid: 0, // Wildcard UID
  tokenExpireSeconds: 3600,
);

2. RTM Tokens for Real-Time Messaging #

String rtmToken = RtmTokenBuilder.buildToken(
  appId: 'your_app_id',
  appCertificate: 'your_app_certificate',
  userId: 'user_unique_id',
  tokenExpireSeconds: 86400, // 24 hours
);

3. Multi-Service Tokens (Advanced) #

For applications that need both RTC and RTM services:

import 'package:agora_token_generator/agora_token_generator.dart';

String generateMultiServiceToken() {
  const String appId = 'your_app_id';
  const String appCertificate = 'your_app_certificate';
  const String channelName = 'multi_service_channel';
  const String userId = 'user123';
  const int uid = 12345;
  const int expireSeconds = 3600;

  // Create access token
  var token = AccessToken(appId, appCertificate, expireSeconds);

  // Add RTC service with permissions
  var rtcService = ServiceRTC(channelName, uid.toString());
  rtcService.addPrivilege(Privileges.JOIN_CHANNEL, expireSeconds);
  rtcService.addPrivilege(Privileges.PUBLISH_AUDIO_STREAM, expireSeconds);
  rtcService.addPrivilege(Privileges.PUBLISH_VIDEO_STREAM, expireSeconds);
  token.addService(rtcService);

  // Add RTM service
  var rtmService = ServiceRTM(userId);
  rtmService.addPrivilege(Privileges.LOGIN, expireSeconds);
  token.addService(rtmService);

  return token.build();
}

🛠️ Advanced Configuration #

Token Expiration Best Practices #

class TokenConfig {
  // Short-lived tokens for production (recommended)
  static const int shortLived = 3600;    // 1 hour
  static const int mediumLived = 7200;   // 2 hours
  static const int longLived = 86400;    // 24 hours

  // For development/testing only
  static const int development = 2592000; // 30 days
}

Error Handling #

String? generateTokenSafely({
  required String appId,
  required String appCertificate,
  required String channelName,
  required int uid,
}) {
  try {
    if (appId.isEmpty || appCertificate.isEmpty) {
      throw ArgumentError('App ID and Certificate cannot be empty');
    }

    return RtcTokenBuilder.buildTokenWithUid(
      appId: appId,
      appCertificate: appCertificate,
      channelName: channelName,
      uid: uid,
      tokenExpireSeconds: 3600,
    );
  } catch (e) {
    print('❌ Token generation failed: $e');
    return null;
  }
}

Flutter Integration Example #

class AgoraTokenService {
  static const String _appId = 'YOUR_APP_ID';
  static const String _appCertificate = 'YOUR_APP_CERTIFICATE';

  static Future<String> getRtcToken({
    required String channelName,
    required int uid,
    int expireSeconds = 3600,
  }) async {
    return RtcTokenBuilder.buildTokenWithUid(
      appId: _appId,
      appCertificate: _appCertificate,
      channelName: channelName,
      uid: uid,
      tokenExpireSeconds: expireSeconds,
    );
  }

  static Future<String> getRtmToken({
    required String userId,
    int expireSeconds = 3600,
  }) async {
    return RtmTokenBuilder.buildToken(
      appId: _appId,
      appCertificate: _appCertificate,
      userId: userId,
      tokenExpireSeconds: expireSeconds,
    );
  }
}

🎮 Interactive Demo #

This package includes a comprehensive Flutter Web demo that showcases:

🎛️ Interactive Token Generator - Generate tokens with a modern UI
📺 Video Conference Simulator - See how tokens work in real-time
🔐 Security Best Practices - Learn about proper token handling
📱 Responsive Design - Works on all screen sizes

Running the Demo #

cd example
flutter run -d chrome --web-port=8080

Visit http://localhost:8080 to try the interactive demo!

🔐 Getting Agora Credentials #

Step 1: Create Agora Account #

Visit Agora Console
Sign up for a free account
Complete email verification

Step 2: Create Project #

Click "Create Project" in the console
Choose "Secured mode: APP ID + Token"
Note down your App ID

Step 3: Generate App Certificate #

Go to your project settings
Click "Generate" next to App Certificate
⚠️ Keep your App Certificate secure - never expose it in client code!

Step 4: Test Connection #

// Test with the provided demo credentials (for testing only)
const demoAppId = '970CA35de60c44645bbae8a215061b33';
const demoAppCertificate = '5CFd2fd1755d40ecb72977518be15d3b';

🏗️ Token Architecture #

AccessToken2 (007) Format #

This package implements Agora's latest token format with enhanced security:

Header: Token version and algorithm
Payload: Encrypted service privileges and metadata
Signature: HMAC-SHA256 signature for verification

Supported Services & Privileges #

Service	Privileges	Description
RTC	`JOIN_CHANNEL`	Join audio/video channel
RTC	`PUBLISH_AUDIO_STREAM`	Publish audio stream
RTC	`PUBLISH_VIDEO_STREAM`	Publish video stream
RTC	`PUBLISH_DATA_STREAM`	Publish data stream
RTM	`LOGIN`	Login to messaging service

🔧 API Reference #

RtcTokenBuilder #

`buildTokenWithUid()`

static String buildTokenWithUid({
  required String appId,
  required String appCertificate,
  required String channelName,
  required int uid,
  required int tokenExpireSeconds,
})

`buildTokenWithAccount()`

static String buildTokenWithAccount({
  required String appId,
  required String appCertificate,
  required String channelName,
  required String account,
  required int tokenExpireSeconds,
})

RtmTokenBuilder #

`buildToken()`

static String buildToken({
  required String appId,
  required String appCertificate,
  required String userId,
  required int tokenExpireSeconds,
})

AccessToken #

Constructor

AccessToken(String appId, String appCertificate, int expireSeconds)

Methods

void addService(Service service)
String build()

🚨 Security Best Practices #

✅ Do's #

✅ Generate tokens on your backend server
✅ Use short-lived tokens (1-2 hours max)
✅ Implement token refresh mechanism
✅ Validate user permissions before token generation
✅ Use HTTPS for token transmission
✅ Log token generation for audit trails

❌ Don'ts #

❌ Never expose App Certificate in client code
❌ Don't use long-lived tokens in production
❌ Don't generate tokens on client devices
❌ Don't share tokens between different users
❌ Don't ignore token expiration

Recommended Architecture #

[Mobile App] -> [Your Backend API] -> [Agora Token Generator] -> [Agora Services]

🤝 Contributing #

Contributions are welcome!

📄 License #

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments #

Agora.io - For providing the real-time communication platform
Flutter Team - For the amazing cross-platform framework
Dart Community - For the robust language and ecosystem
🐛 Issues: GitHub Issues
📧 Email: developer@agora.io

Made with ❤️ for the Flutter community

⭐ Star on GitHub • 📦 View on Pub.dev

agora_token_generator 1.0.0 agora_token_generator: ^1.0.0 copied to clipboard

Metadata