تخطَّ إلى المحتوى
Documentation

رموز الانضمام الخاصة بـ RTC

يحتاج المشارك إلى بيانات اعتماد قصيرة الأمد للانضمام إلى غرفة. يمكن لخادمك الخلفي الحصول عليها بطريقتين:

الطريقةكيفاستخدم هذه الطريقة عندما
المعتمدة من الخادمتقوم الخلفية الخاصة بك بالاتصال POST /v1/rooms/{roomId}/tokens باستخدام APIمفتاحالافتراضي. APIاستدعاء واحد لكل عملية انضمام.
الإنشاء دون اتصال بالإنترنتتقوم الخلفية الخاصة بك بتوقيع رمز الانضمام باستخدام مفتاح توقيع المشروع، دون استدعاء RTC؛ ويتم تبادل الرمز عند POST /v1/joinعند ارتفاع أحجام عمليات الانضمام، أو عندما لا ينبغي للخلفية الخاصة بك استدعاء RTC عند كل عملية انضمام

كلاهما يمنحان نفس بيانات الاعتماد ويطبقان نفس فحوصات حالة الغرفة وسعتها وخطة الخدمة. في كلتا الحالتين تقرر الخلفية الخاصة بك من يمكنه الانضمام إلى أي غرفة؛ لا تسمح أبدًا للعميل باختيار غرفته أو دوره أو أذوناته بنفسه.

بيانات الاعتماد الصادرة عن الخادم

Section titled “بيانات الاعتماد الصادرة عن الخادم”
Terminal window
curl --fail-with-body \
--request POST "https://api.rtc.champrep.com/v1/rooms/$RTC_ROOM_ID/tokens" \
--header "Authorization: Bearer $RTC_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"canPublish":true}'

يحتاج المفتاح إلى tokens:write نطاق المطالبات. تحتوي الاستجابة على token, participantId, url, iceServers و expiresIn؛ انظر API مرجع و تدفق الانضمام.

مفاتيح التوقيع الخاصة بالمشروع

Section titled “مفاتيح التوقيع الخاصة بالمشروع”

ينتمي مفتاح التوقيع إلى مشروع واحد. ويكون id هو JWT kid.

الخوارزميةما يحتفظ به RTCما تحتفظ به
HS256 (افتراضي)السر المشترك، المشفرالسر rtcsk_…، تُعرض مرة واحدة عند الإنشاء
ES256المفتاح العام P-256المفتاح الخاص: يتم إنشاؤه بواسطة RTC ويتم عرضه مرة واحدة كـ JWK، أو مفتاحك الخاص (تقوم بإرسال JWK العام فقط)

قم بإنشاء المفاتيح في وحدة التحكم RTC، أو باستخدام جلسة عمل وحدة التحكم الخاصة بك من خلالAPI:

الطريقة والمسارالنتيجة
GET /v1/projects/{projectId}/signing-keysالمفاتيح: id, name, algorithm, prefix (HS256) أو publicKeyJwk (ES256)، createdAt, expiresAt, revokedAt, lastUsedAt
POST /v1/projects/{projectId}/signing-keys201، المفتاح، ومرة واحدة، secret (HS256) أو privateKeyJwk (ES256، مُولَّد)
DELETE /v1/projects/{projectId}/signing-keys/{keyId}{ "revoked": true }؛ تتوقف الرموز الموقعة به عن العمل فورًا

نص إنشاء هو { "name", "algorithm"?, "publicKeyJwk"?, "expiresInDays"? }. expiresInDays تقبل القيم من 1 إلى 730؛ وبدونها لا تنتهي صلاحية المفتاح. يمكن أن يحتوي المشروع على ما يصل إلى خمسة مفاتيح نشطة (SIGNING_KEY_LIMIT). احتفظ بالمفتاح السري أو المفتاح الخاص في مدير الأسرار الخاص بخادمك فقط: لا تضعه أبدًا في متصفح أو تطبيق جوال أو مستودع أو دردشة. يمكن للمساعدCHAMPREP AI إدراج قائمة بمفاتيح التوقيع الخاصة بك، لكنه لا ينشئ مفتاحًا أبدًا ولا يعرض أي سر.

للتناوب، قم بإنشاء مفتاح جديد، ونشره، ثم قم بإلغاء المفتاح القديم.

رمز الانضمام هو JWT موقّع بمفتاح توقيع المشروع.

الجزءالحقلالقواعد
رأس الرسالةalgHS256 أو ES256، خوارزمية المفتاح
رأس الرسالةkidمفتاح التوقيع id
المطالباتaudدائمًا rtc-join
المطالباتroomIdالغرفة في مشروع المفتاح
المطالباتiat, expأوقات الإصدار وانتهاء الصلاحية بالثواني؛ بفارق ساعة واحدة كحد أقصى
المطالباتjtiمعرف فريد، من 8 إلى 128 حرفًا (A-Z a-z 0-9 . _ : -)؛ يمكن استخدام كل رمز مرة واحدة
المطالبات (اختياري)sub أو identityمعرف المستخدم الثابت الخاص بك (A-Z a-z 0-9 : _ -، بحد أقصى 128)؛ إذا تم تعيين كليهما، فيجب أن يتطابقا
المطالبات (اختياري)nameالاسم المعروض للمشاركين الآخرين، بحد أقصى 80 حرفًا
المطالبات (اختياري)rolehost, cohost, participant, panelist أو attendee
المطالبات (اختياري)permissions, canPublishما يمكن للمشارك نشره، كما هو الحال في طلب رمز REST
المطالبات (اختياري)metadataسلسلة نصية خاصة بك، بحد أقصى 1 كيلوبايت، مرئية للمشاركين الآخرين
المطالبات (اختياري)ttlSecondsمدة صلاحية بيانات اعتماد الوسائط التي يعيدها التبادل، من 30 إلى 300
المطالبات (اختياري)transcribefalse: هذا المشارك لا يتم نسخ؛ يتم تسجيل مساراتها ولكن يتم تخطيها في النص المكتوب

اجعل مدة صلاحية الرمز قصيرة (بضع دقائق كافية لعملية الانضمام). أي رمز منتهي الصلاحية، أو معاد استخدامه، أو موقّع بشكل خاطئ، سيؤدي إلى 401 JOIN_GRANT_INVALID أو 409 JOIN_GRANT_USED.

import { randomUUID } from 'node:crypto';
import { SignJWT, importJWK } from 'jose';
// HS256: the key is the UTF-8 bytes of the whole rtcsk_ secret.
const alg = 'HS256';
const key = new TextEncoder().encode(process.env.RTC_SIGNING_SECRET);
// ES256 instead:
// const alg = 'ES256';
// const key = await importJWK(JSON.parse(process.env.RTC_SIGNING_PRIVATE_JWK), 'ES256');
export async function mintJoinToken({ roomId, userId, displayName }) {
return new SignJWT({ roomId, name: displayName, role: 'participant', canPublish: true })
.setProtectedHeader({ alg, kid: process.env.RTC_SIGNING_KEY_ID })
.setAudience('rtc-join')
.setSubject(userId)
.setIssuedAt()
.setExpirationTime('5m')
.setJti(randomUUID())
.sign(key);
}
import json
import os
import time
import uuid
import jwt # pip install "pyjwt[crypto]"
# HS256: the key is the whole rtcsk_ secret.
KEY = os.environ["RTC_SIGNING_SECRET"]
ALGORITHM = "HS256"
# ES256 instead:
# KEY = jwt.PyJWK(json.loads(os.environ["RTC_SIGNING_PRIVATE_JWK"])).key
# ALGORITHM = "ES256"
def mint_join_token(room_id: str, user_id: str, display_name: str) -> str:
now = int(time.time())
claims = {
"aud": "rtc-join",
"roomId": room_id,
"sub": user_id,
"name": display_name,
"role": "participant",
"canPublish": True,
"iat": now,
"exp": now + 300,
"jti": str(uuid.uuid4()),
}
return jwt.encode(claims, KEY, algorithm=ALGORITHM, headers={"kid": os.environ["RTC_SIGNING_KEY_ID"]})

POST /v1/join مع { "token": "<join token>" } تُرجع نفس النص الأساسي مثل POST /v1/rooms/{roomId}/tokens. ولا تحتاج إلى مفتاحAPI: رمز الانضمام هو التفويض.

Terminal window
curl --fail-with-body \
--request POST https://api.rtc.champrep.com/v1/join \
--header 'Content-Type: application/json' \
--data "{\"token\":\"$RTC_JOIN_TOKEN\"}"

قم بتبادل رمز الانضمام من الخادم الخاص بك، أو قم بترحيل التبادل من خلاله: تقبلAPI RTC طلبات المتصفح فقط من وحدات التحكم الخاصة CHAMPREPبـ، لذا فإن POST /v1/join يتم رفض أي طلبات تُرسَل بواسطة متصفح من نطاقك. أرسل بيانات الاعتماد المتبادلة فقط إلى المستخدم الذي تم إنشاء الرمز الخاص به، عبر اتصالك المصادق عليه، وتعامل مع الرمز وبيانات الاعتماد على أنها معلومات سرية. قم بإنشاء رمز انضمام جديد لكل عملية انضمام وإعادة اتصال.