RealtimeKit 참가 토큰의 입장 가능 시간을 지정할 수 있게 됐지만, 새 토큰을 발급하는 갱신과 이전 토큰을 회수하는 작업은 별도로 봐야 해요. Cloudflare는 2026년 11월 12일 사용자 지정 유효시간과 개별 토큰 회수를 발표했습니다. 현재 문서는 갱신해도 기존 토큰은 자신의 만료 시각까지 유효하다고 설명합니다.
이 글은 RealtimeKit SDK로 수업·면접·웹 회의를 만드는 개발자를 위한 안내예요. 11월 16일 공지와 Participant 문서를 다시 확인했습니다. 아래 수업과 시간 예시는 가상 설계 상황이며 실제 참가자에게 토큰을 발급하거나 차단·과금 동작을 시험한 사례는 아닙니다.
참가자 신원과 회의 화면을 연결하는 토큰이에요
RealtimeKit에서는 사용자가 SDK로 회의에 들어오기 전에 백엔드가 해당 회의에 사용자를 참가자로 추가합니다. Add Participant API의 결과에는 회의 안에서의 참가자를 식별하는 ID와 인증 토큰이 포함돼요. 프런트엔드는 이 참가자 인증 토큰을 SDK에 전달해 회의에 입장합니다.
문서는 참가자 토큰을 JWT라고 설명합니다. meetingId와 participantId가 한 회의의 한 참가자에 범위를 정해요. 사용자가 어떤 회의와 어떤 참가자로 들어오는지 확인하는 재료이지, 화면에 보이는 회의 이름이나 사람이 적은 별명만으로 입장 권한을 판단하는 구조는 아닙니다.
참가자를 추가할 때 선택하는 preset은 역할과 권한, 회의 경험을 정합니다. 토큰을 받을 사용자를 확인하는 일과 어떤 역할을 부여할지 정하는 일도 함께 검토할 부분이에요. 이 글에서는 실제 preset을 바꾸거나 특정 역할에 필요한 권한을 부여하지 않았습니다.
백엔드가 Cloudflare API를 호출할 때 쓰는 인증과 프런트엔드가 회의 참가에 사용하는 토큰도 구분해 주세요. 공지의 API 호출 인증 헤더와 참가자에게 반환되는 토큰은 쓰임이 다릅니다. 개발 기록을 남긴다는 이유로 API 비밀값이나 참가자 토큰 원문을 공개하는 방식은 피해야 합니다.
현재 문서는 유효한 토큰을 가진 참가자가 같은 회의의 여러 라이브 세션에 걸쳐 참여할 수 있다고 설명합니다. 한 번 화면에서 나갔다는 사실만으로 해당 토큰의 모든 재입장 가능성이 끝났다고 판단하지 않을 이유예요. 회의 세션의 상태와 토큰의 유효 상태를 별도의 항목으로 기록할 수 있습니다.
두 시간 필드와 생략했을 때의 값을 같이 봐요
사용자 지정 유효시간에는 not_before와 expires_on이 쓰입니다. 전자는 유효해지기 시작하는 때, 후자는 만료되는 때를 나타내요. 참가자를 추가하는 요청의 token 객체나 토큰을 갱신하는 요청 본문에서 지정할 수 있다고 현재 문서가 안내합니다.
두 필드는 모두 선택 사항입니다. not_before를 생략하면 현재 시각이 기본이며 과거 시각을 지정하는 것도 허용합니다. expires_on의 기본값은 not_before에 100일을 더한 시각이고 미래여야 합니다. 유효 구간의 길이는 100일을 넘을 수 없다고 설명해요. 기본값을 바꾸지 않은 기존 연결은 계속 100일 토큰을 받는다는 것이 공지의 조건입니다.
따라서 시작 시각만 지정했다고 만료도 수업 종료 시각에 맞춰졌다고 생각하면 안 됩니다. 필요한 구간이 짧다면 두 필드의 실제 결과를 함께 확인할 문제예요. 반대로 만료 시각만 남겼을 때 시작이 언제인지도 응답과 기본값을 기준으로 읽어야 합니다.
날짜 형식에는 시간대가 포함된 RFC 3339 타임스탬프를 사용합니다. 예를 들어 가상의 한국시간 오후 3시 수업을 2026-11-17T15:00:00+09:00처럼 표현할 수 있어요. 같은 순간은 UTC로 오전 6시입니다. 날짜와 시각만 쓰고 어느 시간대인지 빠뜨리면 서로 다른 약속을 적게 될 수 있습니다.
API 응답은 발급된 토큰의 두 시각을 UTC로 돌려줍니다. 화면에 보여 주는 한국시간과 저장·응답의 UTC를 같은 시각으로 환산해 대조해 주세요. 여기서는 가상 예시의 시차를 설명했을 뿐 실제 서비스의 발급 결과를 관찰한 것은 아닙니다. 사용자 안내와 서버의 실제 값을 함께 검토할 항목으로 남기는 것이 목적입니다.
갱신은 이전 토큰을 없애는 동작이 아니에요
백엔드는 토큰이 만료되기 전이나 후에 Refresh Participant Token 엔드포인트를 호출할 수 있습니다. 새 토큰은 기존 참가자 레코드를 사용하며 참가자 ID와 preset도 유지한다고 문서가 설명해요. 새 값을 받았다는 사실을 참가자의 역할을 새로 검토했다는 증거로 쓰지는 않아야 합니다.
중요한 조건은 갱신이 이전에 발급된 토큰을 무효로 만들지 않는다는 점입니다. 각각의 토큰은 자신의 만료 시각까지 유효합니다. 새 토큰의 시간을 짧게 정했다고 이미 길게 발급한 옛 토큰의 유효 구간까지 함께 짧아졌다고 설명하면 안 돼요.
가상의 수업 참가자에게 처음에는 긴 토큰을 주고 뒤에 수업 시간에 맞춘 새 토큰을 줬다고 해 볼게요. 새 토큰으로 입장한 화면만 확인하면 이전 토큰의 상태를 놓칠 수 있습니다. 문서의 조건에 따라 이전 토큰이 여전히 유효할 수 있다는 점을 운영 설계에 남겨야 합니다. 이는 실제 유출이나 재입장 사건을 재현한 사례가 아닙니다.
갱신 API를 호출할 수 있다는 설명은 아무 사용자에게나 재발급해도 된다는 뜻이 아닙니다. 내 애플리케이션에서 현재 사용자가 해당 수업·면접에 참여할 자격이 있는지 확인하고 발급하는 절차는 별도로 설계할 부분이에요. 도구가 반환하는 신원 정보와 서비스에서 판단한 이용 자격을 구분하는 제안입니다.
기록에는 발급·갱신 시각, 대상 회의와 참가자, 응답의 유효 구간, 어떤 정책을 적용했는지 남길 수 있습니다. 실제 토큰 문자열 대신 노출하지 않아도 상태를 추적할 수 있는 식별 방식을 검토해 주세요. 토큰 원문을 작업 문서에 늘어놓지 않고도 여러 발급 결과의 유효 구간을 비교할 방법을 정하는 것입니다.
개별 회수와 참가자 삭제는 영향을 나눠 보세요
새 개별 회수 기능은 특정 토큰 하나를 대상으로 합니다. 문서는 요청 본문에 회수할 토큰을 보내는 DELETE 경로를 안내하며, 같은 참가자에게 발급된 다른 토큰은 계속 유효하다고 설명해요. 참가자라는 이름이 같다는 이유로 그 사람의 모든 토큰이 함께 사라졌다고 기록할 수 없습니다.
또한 회수한 토큰이 모든 위치에서 거절되기까지 최대 60초가 걸릴 수 있다고 명시합니다. 이 시간에는 회수된 토큰으로 다시 입장할 가능성이 있습니다. 회수 요청이 받아들여진 사실과 즉시 모든 장소에서 재입장이 막혔다는 사실을 같은 확인으로 표현하지 않는 편이 좋습니다.
문서는 모든 참가자 토큰의 접근을 즉시 막아야 한다면 참가자를 삭제하는 경로를 사용하라고 설명합니다. 개별 토큰 회수와 참가자 삭제는 대상으로 삼는 범위가 달라요. 회의 전체를 INACTIVE로 바꾸지 않고 단일 토큰을 회수할 수 있다는 공지와도 구분해 읽어 주세요.
현재 Participant 문서는 토큰을 회수하거나 참가자를 삭제할 때 활성 세션에 있는 해당 참가자도 제거한다고 안내합니다. 따라서 접속 중인 사람에게 미치는 영향까지 생각해야 합니다. 이 글은 운영 회의에서 삭제를 실행하라는 지시가 아니며 승인된 시험 환경에서 어떤 효과를 확인할지 정리하는 안내입니다.
회수·삭제를 설계할 때는 누가 결정하는지, 사용자에게 어떤 안내를 보여 줄지, 다시 참가를 허용해야 할 때 어떤 승인 절차를 따를지도 함께 정해 보세요. 이미 회수한 토큰이 화면 새로고침만으로 복구됐다고 가정하지 않는 편이 좋습니다. 사용자 자격 재확인과 실제 재입장 결과를 별도로 관찰할 문제입니다.
입장 거절 이유와 요금 설명의 범위를 확인해요
만료됐거나 아직 유효하지 않거나 회수된 토큰으로는 회의에 들어갈 수 없습니다. 현재 문서는 UI와 Core SDK가 토큰을 유효하지 않은 것으로 보고하며, 회의 단계에 진입하기 전에 거절하기 때문에 해당 참가에 대해 요금이 청구되지 않는다고 설명합니다. 이것을 애플리케이션의 모든 요청·기존 사용량이 무료라는 뜻으로 넓히지 않아야 합니다.
API 오류의 reason에는 participant_token_expired, participant_token_not_yet_valid, participant_token_revoked, participant_token_invalid가 나열됩니다. 관찰한 이유에 따라 시간 설정을 볼지, 회수 상태를 볼지 질문을 나눌 수 있어요. 오류 문자열을 임의로 번역해 원래 조건을 잃지 않는 편이 좋습니다.
예를 들어 시작 전의 입장 실패라면 not_before와 시간대의 환산을 대조할 수 있습니다. 오래된 토큰의 실패라면 그 토큰의 만료 시각과 갱신·회수 기록을 살펴볼 수 있겠죠. 이는 기록을 읽는 가상 진단 분기이며 모든 실패가 언제나 그 한 원인으로 생긴다는 주장은 아닙니다.
문서의 custom_participant_id도 함께 구분해 주세요. 내 시스템 사용자와 RealtimeKit 참가자를 연결해 기록을 해석하는 값이며 접근을 제어하는 데 사용되지 않는다고 명시합니다. 이름이나 내부 식별자가 기록돼 있다는 사실만으로 현재 입장 권한이 검증된 것은 아니에요.
공식 안내는 이 식별자에 이메일·전화번호 같은 개인정보를 쓰지 말고 내부 ID나 UUID를 사용하도록 권합니다. 실제 운영 기록에는 원문 토큰과 불필요한 개인 정보를 남기지 않고도 오류·대상·시각을 대조할 범위를 정할 수 있습니다. 제품의 기능 설명과 내 서비스의 데이터 취급 정책은 함께 확인할 대상입니다.
수업 예약 전에 네 가지 상태를 적어 보세요
도입 메모에서는 먼저 서비스에서 정한 수업·면접 일정과 사용자 자격을 적고, 실제 토큰의 시작·만료 시각을 대조해 보세요. 다음에는 갱신해 남아 있는 다른 토큰이 있는지, 회수할 대상이 한 토큰인지 전체 참가자인지를 구분합니다. 마지막으로 실제 입장과 거절을 어떤 환경에서 확인했는지 남기는 방식입니다.
토큰의 유효시간을 수업 시간에 맞추는 설계와 회의 세션 종료를 같은 작업으로 기록하지 않는 편이 좋습니다. 유효시간은 문서의 입장 검증 조건으로 확인하고, 접속 중 참가자 제거는 회수·삭제에 대한 별도 설명과 실제 검토 범위에 연결해야 해요. 이 글에서는 자동 회의 종료 동작을 시험하지 않았습니다.
자주 묻는 질문도 묶어 볼게요. 시간을 생략하면 짧은 토큰이 되나요? 현재 기본값은 100일입니다. 새 토큰을 받으면 이전 토큰이 폐기되나요? 각각 자신의 만료까지 유효합니다. 하나를 회수하면 모든 토큰이 즉시 막히나요? 다른 토큰의 유효성과 최대 60초 전파 조건, 참가자 삭제의 범위를 따로 봐야 합니다.
이번 변경은 회의 참가에 허용할 시간을 더 구체적으로 정할 선택지를 제공합니다. 유효 구간과 사용자 자격, 갱신·회수의 대상, 실제 관찰한 입장 결과를 나누어 남겨 보세요. 설정을 입력했다는 사실을 즉시 차단이나 전체 회의 보안 검증으로 과장하지 않는 기록이 다음 구현과 사용자 안내를 준비하는 데 도움이 됩니다.
자료 확인일은 2026년 11월 16일입니다. 공식 발표와 현재 문서로 확인한 범위를 정리했으며 실제 계정 설정 변경·명령 실행·성능 시험은 하지 않았어요. 적용 시점의 계정·버전·환경 조건은 담당자가 다시 확인해 주세요.
함께 읽어 볼 글: RealtimeKit의 음소거·소음 제거와 미디어 생명주기 안내. 이번 글과 적용 질문이 어떻게 다른지 함께 살펴보세요.

'소프트웨어개발' 카테고리의 다른 글
| D1 가상 테이블 내보내기 지원: SQLite 확인용 덤프와 복원을 구분하세요 (0) | 2026.11.17 |
|---|---|
| GitHub AI Scan 관리 API 추가: 설정 켜기와 검사 완료는 달라요 (0) | 2026.11.17 |
| EmbeddingGemma 2가 Workers AI에 왔어요: 검색 전 차원과 입력을 맞추세요 (0) | 2026.11.17 |