API 키 및 인증

Telemetry API는 익명 체험 키와 팀 API 키를 받습니다. 키는 비공개로 보관하고 신뢰할 수 있는 서버 코드에서만 사용하세요. 단 하나의 예외는 수집 전용 키입니다. 이벤트 전송만 할 수 있으므로 브라우저, 모바일 앱, CLI에 넣어도 안전합니다.

익명 키로 시작하기

홈페이지의 설정 프롬프트에는 anon_… 키가 있습니다. 계정 없이 이벤트 수집, SQL 쿼리, 테이블 메타데이터 조회가 가능합니다. 쿼리는 첫 이벤트 이후 24시간 동안 사용할 수 있습니다. 데이터를 유지하려면 7일 이내에 계정을 만드세요. 이벤트가 없는 체험은 생성 후 7일이 지나면 만료됩니다.

가입 시 같은 브라우저의 체험을 감지합니다. 브라우저를 바꿨거나 비공개 연결 링크를 잃었다면 **익명 API 키가 있나요?**를 선택하고 키를 붙여 넣은 뒤 내 데이터 찾기를 누르세요. 가입하거나 기존 계정으로 로그인한 뒤 내 데이터 유지에서 연결을 확인하세요. 이벤트는 원래 워크스페이스에 남고 기존 키는 계속 작동합니다. 만료된 체험은 복구할 수 없습니다.

계정 키 관리하기

용도별로 키를 만들고 필요한 최소 권한만 부여하세요. 버전 관리 밖에 저장하고 해당 작업을 중단하면 키를 폐기하세요.

팀 설정 → API 키를 열어 키를 생성하거나 관리하세요. 전체 값은 자격 증명이므로 공유 문서나 이슈가 아닌 대상 비밀 관리자에 복사하세요.

가장 좁은 범위를 선택하세요

Telemetry는 세 가지 범위를 지원합니다.

이벤트만 보내는 애플리케이션에는 ingest가 필요합니다. 보고 작업에는 read가 필요합니다. 데이터 삭제, 보존 기간이나 파티션 변경, 테이블 삭제, 대시보드와 알림 생성·변경은 read-and-write 키만 할 수 있으므로 브라우저, 모바일 애플리케이션, 공개 저장소, 사용자 작성 스크립트에 절대 넣지 마세요. 2026년 10월 이전에 '쓰기 전용'으로 만든 키는 이제 ingest 키입니다.

키 보내기

HTTP 엔드포인트는 키를 원시 Authorization 값 또는 전달자 토큰으로 허용합니다.

curl https://api.telemetry.sh/tables \
  -H "Authorization: Bearer $TELEMETRY_API_KEY"

SDK 초기화에도 같은 API 키를 사용합니다. 서버 코드에서는 환경 변수나 비밀 관리 도구에서 키를 읽으세요:

import telemetry from "telemetry-sh";

telemetry.init(process.env.TELEMETRY_API_KEY);

익명 체험 키, read 키, read-and-write 키를 NEXT_PUBLIC_ 같은 공개 빌드 변수나 클라이언트 설정에 넣지 마세요. 이벤트만 보내는 클라이언트에는 ingest 키를 사용할 수 있습니다. 팀 설정 → API 키에서 Ingest only 권한으로 생성하고 공개 빌드에 넣기 전에 권한을 확인하세요.

수집 전용 키로는 보낸 이벤트를 조회하거나 작업 공간을 관리할 수 없습니다. Telemetry 대시보드에서 앱의 이벤트를 확인하거나 신뢰할 수 있는 서버 스크립트에서 별도의 read 키로 확인하세요. 읽기 키를 클라이언트에 넣지 마세요. 전송하려는 필드만 기록하세요. 쓰기 전용 키라도 개인적인 데이터를 수집하는 것이 안전해지는 것은 아닙니다.

워크로드별로 키 분리

프로덕션 수집, 준비, 예약된 보고 및 코딩 에이전트 설정에 고유 키를 사용합니다. 워크로드별 키는 순환 및 사고 대응을 더 작게 만듭니다. 하나의 보고 키를 취소해도 이벤트 수집이 중단되어서는 안 됩니다.

소유자와 목적에 따라 키 이름을 지정하세요. 키 값 자체를 기록하지 않고 키가 배포된 위치, 범위, 예상 순환 소유자를 기록합니다.

안전하게 순환 및 취소

먼저 대체 키를 생성하여 워크로드에 배포하고 성공적인 요청을 확인한 후 이전 키를 취소합니다. read-and-write 키를 순환할 때 수집 및 쿼리 경로를 모두 실행합니다.

비공개 키가 커밋, 로그, 스크린샷, 프롬프트 또는 공개 클라이언트 번들에 포함되면 유출된 것으로 간주하세요. 즉시 폐기하고 교체한 뒤 해당 팀의 테이블과 조회 활동을 확인하세요. 공개 클라이언트에 의도적으로 포함한 ingest 키는 여전히 쓰기 전용이지만 복사한 사람은 누구나 이벤트를 보낼 수 있습니다. 악용되고 있다면 폐기하고 교체하세요.

로그 API, 쿼리 API 및 민감한 데이터 지침을 계속 진행하세요.