공개 API & API 키

1. 개요

MousePlayer API로 워크스페이스의 데이터를 자체 대시보드, 데이터 웨어하우스 또는 내부 도구로 가져올 수 있습니다. 세션에 고객 ID를 연결하는 기능(identify, 쓰기 범위의 키 필요, 키 범위 참조)을 제외하면 읽기 전용입니다. API로 데이터를 수정하거나 삭제할 수 없습니다.

• 기본 URL: https://www.mouseplayer.com/api/v1/
• 모든 응답은 JSON입니다.
• 모든 요청은 API 키로 인증되며, 해당 키가 속한 워크스페이스로 범위가 자동 제한됩니다 — 한 워크스페이스의 키로 다른 워크스페이스의 데이터를 보는 것은 실수로도 불가능합니다.
• 전체 세션 재생 녹화(마우스 이동, DOM 스냅샷)는 API를 통해 제공되지 않습니다 . 세션 메타데이터, 페이지 조회, 맞춤 이벤트 및 세그먼트를 받습니다 — 원시 재생 데이터를 옮기지 않고도 보고서와 대시보드를 만들기에 충분합니다.

2. 인증

계정 메뉴의 API 키 에서 API 키를 생성하고 관리하세요(/api-keys). 워크스페이스 소유자와 관리자만 키를 생성하거나 폐기할 수 있습니다.

모든 요청의 Authorization 헤더에 키를 Bearer 토큰으로 전송하세요.

누락되거나 형식이 잘못되었거나 폐기된 키에는 401 응답이 반환됩니다.

요금제 요구 사항

REST API는 Business 및 Enterprise 요금제에 포함됩니다. 요금제는 워크스페이스의 소유자 를 기준으로 적용되므로 초대받은 팀원도 이를 따릅니다. 확인은 키 생성 시뿐 아니라 모든 요청에서 실행됩니다 — 워크스페이스 요금제가 낮아지면 기존 키가 작동을 멈추고 403을 반환합니다.

키 범위

각 키는 접두사에 자체 범위를 표시하므로 보는 것만으로 어떤 작업을 하는지 알 수 있습니다 — 예를 들어 .env파일이나 티켓, 터미널에서 확인할 수 있습니다.

3. 요청 한도

각 API 키에는 분당 60개 요청의 한도가 적용되며 이동 시간 창으로 집계합니다. 이를 초과하면 시간 창이 해소될 때까지 요청에 429 응답이 반환됩니다.

4. 엔드포인트

GET/api/v1/projects

워크스페이스의 모든 프로젝트(추적 속성)를 나열합니다.

GET/api/v1/projects/{channelid}/sessions

프로젝트에서 녹화된 방문자 세션을 최신순으로 나열합니다. 페이지 나누기를 지원합니다.

GET/api/v1/sessions/{session_id}

단일 세션의 메타데이터와 페이지 조회입니다. 전체 재생 데이터는 의도적으로 제외합니다 — 녹화 재생에는 대시보드의 플레이어를 사용하세요.

GET/api/v1/sessions/{session_id}/events

세션 중 발생한 맞춤 이벤트( mp('event', ...)로 전송하는 것과 같은 이벤트)와 해당 매개변수입니다.

GET/api/v1/projects/{channelid}/segments

프로젝트에 정의된 방문자 세그먼트를 나열합니다(프로젝트별 세그먼트와 워크스페이스 전체 세그먼트 모두).

5. 백엔드에서 고객 ID 연결

브라우저는 사용자가 누구인지 모르는 경우가 많습니다. B2B 제품에서는 로그인 후 신원이 결정됩니다 — 백엔드에서 결정되는 것입니다. 쇼핑몰에서는 주문 확인 시점입니다. 이 엔드포인트는 바로 그 순간을 위한 것입니다.

POST /api/v1/sessions/{session_id}/identify
Authorization: Bearer mp_live_xxxxxxxxxxxx
Content-Type: application/json

{"user_id": "customer-4711"}

// 200 OK
{"data": {"session_id": "s_a1b2c3", "user_id": "customer-4711",
          "changed": true, "previous": null, "webhook_queued": true}}

그러면 ID가 세션 목록에 표시되어 검색할 수 있게 되며, session_identified 웹훅이 실행됩니다 — 이를 통해 CRM에 전달됩니다.

6. 웹훅: 서명 검증

웹훅은 프로젝트별로 연동에서 설정하며, 서명용 비밀 값도 여기서 확인할 수 있습니다. 모든 전송에는 다음 헤더가 포함됩니다.

서명은 프로젝트의 서명용 비밀 값을 키로 사용하여 timestamp + "." + raw body에 대해 계산한 HMAC-SHA256입니다.

// PHP
$erwartet = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
if (!hash_equals($erwartet, $signature)) { http_response_code(401); exit; }

// Node
const expected = 'sha256=' + crypto.createHmac('sha256', secret)
                                     .update(timestamp + '.' + rawBody).digest('hex');

전송 및 재시도

전송에 실패하면 1분, 5분, 15분, 1시간 및 6시간의 간격으로 재시도한 뒤 포기합니다. 4xx 응답 중 408 및 429 이외의 응답은 재시도하지 않습니다 — 이는 "지금은 안 됨"이 아니라 "이 방식은 안 됨"을 뜻합니다. 응답은 2xx 를 신속히 반환하고 작업은 그 뒤에 수행하세요. 전송은 10초 후 시간 초과됩니다.

사용 가능한 이벤트

7. 오류 & 상태 코드

8. 보안 참고 사항

• 읽기 전용 키(mp_ro_)는 어떤 항목도 변경할 수 없습니다. 쓰기 키(mp_rw_)는 고객 ID 연결만 할 수 있으며, 어떤 키도 데이터를 삭제하거나 원시 재생 데이터를 내보낼 수 없습니다.
• 모든 요청은 키가 속한 워크스페이스로 범위가 자동 제한됩니다 — 다른 워크스페이스 ID를 전달하여 다른 사람의 데이터를 볼 방법은 없습니다.
• 다음 위치에서 언제든지 키를 폐기할 수 있습니다. /api-keys폐기는 즉시 적용됩니다.
• API 키를 비밀번호처럼 취급하세요. 실수로 공개 저장소에 커밋했다면 즉시 폐기하고 새로 만드세요.