최종 업데이트
인증
모든 요청은 워크스페이스 API key를 Bearer 토큰으로 전달합니다. key는 스코프가 지정되고 폐기할 수 있으며, 하나의 워크스페이스 크레딧 지갑에 연결됩니다.
Bearer key
key는 Authorization 헤더에 Bearer <key> 형식으로 보내세요. key는 ttk_live_<id>_<secret> 형태이며, 대시보드에서는 ttk_live_<id> 접두사로 표시됩니다. key는 설정 → API key에서 만들 수 있고, 전체 key는 한 번만 표시됩니다. key는 워크스페이스 소유자를 대신해 동작하며, 부여된 스코프로 제한됩니다.
curl "https://api.toktokdata.live/v1/rankings/regions" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"하나의 지갑
key는 자신을 소유한 워크스페이스의 크레딧을 사용합니다. API 사용량과 대시보드 사용량은 설정 → 사용량에 함께 표시됩니다.
스코프
key는 자신의 스코프가 허용하는 엔드포인트만 호출할 수 있습니다. 작업에 필요한 최소한의 스코프만 선택하세요. 필요하면 언제든 두 번째 key를 만들 수 있습니다. key의 스코프를 벗어난 요청과 대시보드 전용 경로(관심 목록, 방, 워크스페이스, 결제)는 403과 코드 insufficient_scope를 반환하며, 해당 모듈이 없는 요금제는 module_not_entitled를 반환합니다.
| 스코프 | 허용 범위 |
|---|---|
live:read | LIVE 세션 목록과 개별 세션, 크리에이터 성과, LIVE 새로고침. LIVE 모듈이 필요합니다. |
rank:read | 공식 랭킹 보드, 지역, 보드 기록. LIVE 모듈이 필요합니다. |
shop:read | 쇼핑 보드(shopping으로 시작하는 board)에도 추가로 필요합니다. |
creator:read | 크리에이터 검색, 프로필, 분석, 변경 내역, 팔로잉, 팔로워, 인사이트. 조회 모듈이 필요합니다. |
content:read | 동영상, 동영상 댓글, 크리에이터의 동영상. 조회 모듈이 필요합니다. |
trend:read | 지역별 트렌드. 조회 모듈이 필요합니다. |
export | 내보내기 생성, 목록 조회, 다운로드. |
webhook:manage | 모든 채널의 알림 규칙과 규칙 테스트. LIVE 모듈이 필요합니다. |
keys:manage | API key 목록 조회, 생성, 폐기, 그리고 이용 권한과 사용량 조회. |
live:stream · gifter:read | 향후 공개될 엔드포인트용으로 예약되어 있으며, 아직 아무 권한도 부여하지 않습니다. |
key 교체
먼저 새 key를 만들어 배포한 다음, 같은 화면에서 이전 key를 폐기하세요. 폐기는 즉시 적용됩니다. 처리 중인 요청은 끝까지 완료되고, 새 요청은 401로 실패합니다.
key를 만들 때 expiresAt 날짜를 지정할 수도 있으며, 그 이후에는 401을 반환합니다.
오류
| 상태 | 코드 | 의미 |
|---|---|---|
| 401 | unauthorized | key가 없거나, 형식이 잘못되었거나, 폐기 또는 만료되었거나, 워크스페이스가 비활성 상태입니다. |
| 403 | insufficient_scope | key는 유효하지만 필요한 스코프가 없거나, 대시보드 전용 경로입니다. |
| 403 | module_not_entitled | 워크스페이스 요금제에 LIVE 또는 조회 모듈이 포함되어 있지 않습니다. |
| 402 | credit_cap_exceeded | 이번 달 크레딧을 모두 사용했습니다. 크레딧과 오류를 참고하세요. |
이 페이지가 도움이 되었나요?