준수 통합 설계

준수 통합 설계

이 페이지는 폴링과 커서 기반 Activity Feed 소비 중에서 선택하고, Compliance API 이벤트를 SIEM과 상관시키며, 보존을 계획하는 방법을 설명해 드릴게요.

Compliance API를 활성화하려면 Compliance API 설정을 참고하세요.

필요한 범위: Compliance Access Key 또는 Admin API 키의 read:compliance_activities.

프로덕션 Compliance API 통합은 세 가지 설계 선택을 해요: Activity Feed를 소비하는 방식, 출력이 SIEM(보안 정보·이벤트 관리) 시스템과 상관되는 방식, 활동·콘텐츠의 장기 사본이 어디 사는지. 이 선택들은 엔드포인트 자체와 독립적이에요. 이 페이지는 그 트레이드오프를 평가하도록 도와드려요.

이 페이지는 다음 페이지를 읽었다고 가정해요:

• 활동 피드 조회 — 전반에 걸쳐 참조하는 매개변수·페이지네이션 계약을 정의.
• 채팅·파일·프로젝트 조회 및 삭제 — 콘텐츠 보존 계획에서 참조하는 채팅·파일·프로젝트 엔드포인트와 deleted_at 의미를 정의.
• 세션 기록 조회 — 로컬·원격 세션 엔드포인트를 정의.

출처: 문서

본문

피드 소비 패턴 선택

Activity Feed는 두 가지 소비 패턴을 지원해요: created_at.gte와 created_at.lt로 경계를 지운 주기적 창 폴링, 그리고 한 응답의 커서를 영속화해 다음 요청에 전달하는 커서 기반 증분 읽기. 둘 다 동일한 Activity 객체를 반환해요. 차이는 클라이언트가 호출 사이에 영속화하는 상태예요.

두 패턴 모두 다음 제약을 공유해요:

• 활동은 발생 후 1분 이내에 조회할 수 있고 6년 동안 보존돼요. 기록은 소급되지 않아요. 조직에 Compliance API가 처음 활성화된 시점부터 시작되며 활성화 이전 활동은 백필되지 않아요.
• 각 페이지의 최대 limit은 5,000.
• 커서 값은 파싱하면 안 되는 불투명 문자열.
• 요청은 상위 조직당 분당 600회로 제한되며 모든 키·연결 조직·모든 /v1/compliance/* 엔드포인트에 걸쳐 공유돼요. 로컬 세션 엔드포인트와 달리 원격 세션 엔드포인트는 그 위에 두 번째 요청 예산을 담아요. 응답 헤더·재시도 계약은 429 Too Many Requests 참고.

창 폴링

created_at.lt를 최소 1분 과거로 설정해 창 안의 모든 활동이 이미 조회 가능하게 하세요. created_at.gte를 하한, created_at.lt를 상한으로 사용해 연속 창이 틈이나 겹침 없이 타일링되게 하고, 이전 창의 lt 값을 다음 창의 gte로 재사용하세요.

curl --fail-with-body -sS -G \
  "https://api.anthropic.com/v1/compliance/activities" \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --data-urlencode "created_at.gte=2026-04-20T07:00:00Z" \
  --data-urlencode "created_at.lt=2026-04-20T08:00:00Z" \
  --data-urlencode "limit=5000"

응답에 has_more: true가 있으면 창에 한 페이지 이상의 활동이 담겨 있어요. 다음 요청에 응답의 last_id를 after_id로 전달해 창 안을 페이지네이션하거나(has_more가 false일 때 중단) 더 작은 시간 창을 선택하세요. 전체 계약은 결과 페이지네이션 참고.

깔끔하게 타일링해도 창이 닫힌 후 색인되는 활동은 이후 창에 절대 나타나지 않아요. 활동 id로 중복 제거하고, 각 새 창을 이전 창과 몇 분 겹치도록 넓히거나 이전 창을 다시 조회하는 주기적 조정 패스를 실행하세요.

현재에 너무 가까운 created_at.lt 경계는 늦게 색인된 활동을 조용히 영구히 버려요. created_at.gte가 그들을 지나 진행되면 이후 창에서 복구할 수 없어요. 1분 조회 가능 수치를 문서화된 색인 지연으로 취급하세요. 부드러운 권장 사항이 아니라.

커서 기반 증분 읽기

first_id="activity_01XyDMpzjS89pFZXqSFUBDr6"  # first_id from a previous response

curl --fail-with-body -sS -G \
  "https://api.anthropic.com/v1/compliance/activities" \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --data-urlencode "limit=5000" \
  --data-urlencode "before_id=$first_id"

has_more가 false가 될 때까지 페이지네이션한 뒤 마지막 응답의 first_id를 영속화하고 다음 실행에 before_id로 그대로 전달해 저장된 커서보다 새로운 활동을 검색하세요. 백필을 위해 반대 방향으로 걷으려면 대신 last_id를 영속화하고 after_id로 전달하세요. 커서·페이지 토큰 전체 참조와 재시도 의미는 결과 페이지네이션 참고.

프로덕션 캐치업 루프는 has_more와 first_id로 반복을 구동해 마지막 폴링 이후 기록된 활동을 가져와요:

cursor = stored_cursor
loop:
  page = GET /v1/compliance/activities?before_id={cursor}&limit=5000
  store(page.data)
  if page.first_id is not null:
    cursor = page.first_id
  if not page.has_more: break
persist(cursor)

커서는 키 교체를 견뎌요. 키 관리 및 교체 참고.

각 페이지는 전달하는 커서에 인접해요. 루프는 현재 지점을 향해 한 페이지씩 앞으로 걸어가요. has_more가 true인 동안 단일 응답을 따라잡은 것으로 취급하지 마세요. has_more가 false가 된 후에만 커서를 영속화하세요. 가져오지 않은 페이지는 이 응답의 first_id와 현재 사이의 더 새로운 페이지이며, 루프를 끝내거나 다시 실행할 때까지 읽히지 않아요.

SIEM과 상관시키기

각 Activity는 SIEM(Splunk, Datadog, Microsoft Sentinel, Cribl 등)에 이미 있는 이벤트와 조인할 수 있는 필드를 담아요:

actor.user_id와 actor.email_address는 actor.type이 user_actor일 때 존재해요. actor.ip_address와 actor.user_agent는 anthropic_actor, scim_directory_sync_actor 같은 일부 actor 유형에는 없어요. 이 필드를 읽기 전에 판별자를 확인하세요. user_id는 사용자 계정의 안정적·불투명 식별자예요. 모든 Compliance API 엔드포인트·활동 페이로드에서 일관되며, 사용자의 이메일·표시 이름이 바뀌어도 변하지 않아요. 기본 조인 키로 email_address가 아니라 user_id를 사용하세요.

Compliance API 자체에 대한 호출은 compliance_api_accessed 활동을 발생시켜요. 다른 활동 유형과 함께 수집해 SIEM이 누가 언제 준수 데이터를 조회했는지 기록하게 하세요. activity_types[]=compliance_api_accessed를 전달해 조회를 범위 지정한 뒤 클라이언트에서 actor.type이 api_actor인 각 활동의 actor.api_key_id를 읽어 접근을 특정 Compliance Access Key나 Admin API 키에 귀속시키세요.

콘텐츠 보존 계획

다섯 가지 보존 지평이 나중에 조회할 수 있는 것을 좌우해요:

Claude Platform의 나머지가 보존을 처리하는 방식은 API 및 데이터 보존 참고.

내보내기·보관과 온디맨드 API 조회 중에서 다음과 같이 선택하세요:

• 활동 메타데이터나 세션 기록에 대한 법적 보존·감사 지평이 6년을 초과하면, Activity Feed 페이지와 세션 기록을 수집하며 자체 아카이브로 내보내세요.
• 콘텐츠 보존 정책이 eDiscovery 지평보다 짧으면 보존 창이 만료되기 전에 채팅·파일 콘텐츠를 내보내세요. Compliance API는 보존이 이미 제거한 콘텐츠를 반환할 수 없어요. 유한 맞춤 기간이 설정된 경우 조직의 커스텀 대화 보존 기간을 따르는 로컬 세션 기록에도 동일하게 적용돼요. 설정이 바뀌는 즉시 로컬 세션 엔드포인트는 조직의 현재 기간보다 오래된 메시지를 반환을 멈추고, 이후 기간을 늘려도 이미 만료된 기록은 복원되지 않으므로 그 이상 보존해야 할 기록은 내보내두세요.
• 사용자가 claude.ai에서 삭제한 후에도 채팅 콘텐츠나 원격 세션 기록을 보존해야 한다면(예: 법적 보존 아래) 채팅·파일·아티팩트·원격 세션 콘텐츠를 수집하며 자체 아카이브로 내보내세요. Compliance API는 사용자가 이미 삭제한 콘텐츠를 반환할 수 없어요.
• 워크플로가 Compliance API 하드 삭제를 발행할 수 있다면(예: DLP 집행) 대상 콘텐츠를 먼저 조회·보관하세요. 하드 삭제 후에는 복구 창이 없어요.

다른 모든 경우에는 직접 API 조회에 의존하고 병렬 사본 유지를 피하세요.

전달 보장과 완전성

Activity Feed를 최소 한 번(at-least-once) 으로 취급하세요. 올바르게 페이지네이션된 순회는 모든 활동을 최소 한 번 반환하지만, 부분 실패 후 재시도는 이미 저장한 활동을 재전달할 수 있어요. 활동 id 필드로 중복 제거하세요.

목록 엔드포인트는 total_count 필드나 체크섬을 반환하지 않아요. 내보내기 실행이 완료되었음을 입증하려면 다음을 기록하세요:

• 시작 커서와 마지막 last_id.
• 내보낸 기록 수.
• 실행 타임스탬프와 마지막 페이지의 request-id.

활동 수는 완전성 검사가 아니에요. claude_chat_viewed 같은 claude_*_viewed 활동 유형은 각 앱의 로딩 패턴을 따라요(Activity 객체 이해하기 참고). 채팅 메시지가 있는데 claude_chat_viewed 활동이 없는 기간 자체로 데이터 누락을 나타내지 않아요. 대신 창 폴링에 설명된 순회와 겹침·조정 패스에 의존하세요.

콘텐츠 엔드포인트(채팅, 파일, 프로젝트, 프로젝트 첨부, 로컬·원격 세션 기록)는 Claude Enterprise 데이터만 제공해요. Activity Feed는 조직 전반의 관리·리소스 이벤트를 표면화해요. Compliance API는 포함하지 않아요:

• Claude Console 또는 API 키로 인증된 Claude API 워크로드의 프롬프트 텍스트·모델 응답.
• Anthropic에 절대 보내지지 않는 로컬 세션의 기기 내 활동(예: Claude가 읽지 않은 로컬 파일).
• Claude Console API 키로 인증되거나 타사 클라우드 플랫폼(Amazon Bedrock, Google Cloud, Microsoft Foundry)을 통해 실행되거나, 사용자 기기 대신 클라우드 인프라에서 실행되는 Claude Code 클라우드 세션에서 실행되는 Claude Code 사용.
• HIPAA 대응이 활성화된 조직의 로컬 세션과 제로 데이터 보존이 적용 중인 로컬 세션.
• 세션 기록 안의 thinking 블록과 이미지·기타 이진 콘텐츠(기록은 사용자 프롬프트·어시스턴트 응답·도구 활동만 담음; 로컬 세션 기록은 이진 콘텐츠가 생략된 곳에 자리 표시자 text 블록을 보여줌).
• 일부 Word·PowerPoint·PDF 업로드처럼 claude.ai가 추출된 텍스트로 저장한 채팅 첨부의 원본 파일(파일 콘텐츠 엔드포인트는 추출된 텍스트를 반환. 파일·아티팩트 조회 참고).
• 로컬 세션의 시스템 프롬프트(마커 메시지가 대신).
• 세션 기록의(로컬·원격) 도구 정의와 MCP 서버 구성, 그리고 로컬 세션 기록의 text 블록에 대한 인용 메타데이터.
• 고객 관리 암호화 키를 현재 사용할 수 없는 조직의 로컬 세션 기록 콘텐츠. 그 요청은 503 Service Unavailable을 반환하고 세션 메타데이터는 여전히 나열돼요.
• 조직의 보존 정책이 제거한 콘텐츠.
• 사용자가 claude.ai에서 삭제한 채팅의 콘텐츠(채팅은 deleted_at이 채워진 채 여전히 나열됨).
• 사용자가 삭제한 원격 세션(삭제된 세션은 더 이상 나열되지 않고 messages 엔드포인트는 404를 반환).
• Compliance API로 하드 삭제된 콘텐츠.

Compliance API가 무엇을 캡처하고 캡처하지 않는지 더 보려면 Compliance API FAQ 참고.

증거의 연속성(chain of custody)을 위해 내보낸 기록을 출처 메타데이터(소스 엔드포인트, 쿼리 매개변수, 실행 타임스탬프, 각 기록의 콘텐츠 해시)와 함께 저장하세요.

다음 단계

• 활동 피드 조회 — 이동 — 필터 매개변수, 페이지네이션, Activity 객체 스키마.
• 채팅·파일·프로젝트 조회 및 삭제 — 이동 — 하드 삭제를 포함한 채팅·파일·프로젝트 엔드포인트.
• 세션 기록 조회 — 이동 — 사용자가 Cowork·Claude Code 같은 Claude 앱·에이전트에서 실행한 세션을 나열하고 기록을 조회하세요.

더 알아보기 (Learn more)

• 활동 피드 조회
• 채팅·파일·프로젝트 조회 및 삭제
• 세션 기록 조회
• Compliance API 오류 처리