---
title: 컴플라이언스 통합 설계하기
url: https://platform.claude.com/docs/ko/manage-claude/compliance-integration-patterns
description: 폴링 방식과 커서 기반 Activity Feed 소비 방식 중에서 선택하고, Compliance API 이벤트를 SIEM과 상관 분석하며, 보존 계획을 수립합니다.
---
Compliance API를 활성화하려면 [Compliance API 설정](https://platform.claude.com/docs/ko/manage-claude/compliance-api-access)을 참조하세요.
**필수 범위:** Compliance Access Key 또는 Admin API 키의 `read:compliance_activities`.
프로덕션 Compliance API 통합은 세 가지 설계 선택을 합니다. Activity Feed를 어떻게 소비할지, 그 출력을 "security information and event management"(보안 정보 및 이벤트 관리), 즉 SIEM 시스템과 어떻게 상관 분석할지, 그리고 활동 및 콘텐츠의 장기 사본을 어디에 보관할지입니다. 이러한 선택은 엔드포인트 자체와는 독립적이며, 이 페이지는 그 트레이드오프를 평가하는 데 도움을 줍니다.
이 페이지는 다음 페이지들을 이미 읽었다고 가정합니다.
* [Activity Feed 쿼리하기](https://platform.claude.com/docs/ko/manage-claude/compliance-activity-feed): 이 문서 전반에서 참조하는 매개변수와 페이지네이션 계약을 정의합니다.
* [채팅, 파일, 프로젝트 조회 및 삭제하기](https://platform.claude.com/docs/ko/manage-claude/compliance-content-data): 채팅, 파일, 프로젝트 엔드포인트와 [콘텐츠 보존 계획하기](https://platform.claude.com/docs/ko/manage-claude/compliance-integration-patterns#plan-content-retention)에서 참조하는 `deleted_at` 의미 체계를 정의합니다.
* [세션 트랜스크립트 조회하기](https://platform.claude.com/docs/ko/manage-claude/compliance-sessions): 로컬 및 원격 세션 엔드포인트를 정의합니다.
## 피드 소비 패턴 선택하기
Activity Feed는 두 가지 소비 패턴을 지원합니다. `created_at.gte`와 `created_at.lt`로 범위를 지정하는 주기적 윈도우 폴링(window polling)과, 한 응답에서 받은 커서를 저장해 다음 요청에 전달하는 커서 기반 증분 읽기(cursor-driven incremental reads)입니다. 두 방식 모두 동일한 `Activity` 객체를 반환하며, 차이점은 호출 사이에 클라이언트가 유지하는 상태입니다.
두 패턴은 다음 제약 조건을 공유합니다.
* 활동은 발생 후 1분 이내에 쿼리 가능해지며 6년간 보존됩니다. 기록은 소급 적용되지 않습니다. 조직에서 Compliance API가 처음 활성화된 시점부터 기록이 시작되며, 활성화 이전의 활동은 백필되지 않습니다.
* 각 페이지의 최대 `limit`은 5,000입니다.
* 커서 값은 파싱해서는 안 되는 불투명한 문자열입니다.
* 요청은 [상위 조직](https://platform.claude.com/docs/ko/manage-claude/compliance-api#how-the-compliance-api-works)당 분당 600건으로 제한되며, 이는 모든 키, 모든 연결된 조직, 모든 `/v1/compliance/*` 엔드포인트에서 공유됩니다. 로컬 세션 엔드포인트와 달리 원격 세션 엔드포인트에는 추가로 두 번째 요청 예산이 적용됩니다. 응답 헤더와 재시도 계약은 [429 Too Many Requests](https://platform.claude.com/docs/ko/manage-claude/compliance-errors#429-too-many-requests)를 참조하세요.
| 패턴 | 선택 기준 |
| ----------- | ------------------------------------------------------------------------------------------------------- |
| 윈도우 폴링 | 파이프라인이 고정된 일정으로 실행되고, 상태 없는(stateless) 워커를 선호하며, 윈도우의 재처리나 중복을 허용할 수 있는 경우 |
| 커서 기반 증분 읽기 | 활동 발생과 파이프라인 수집 사이의 latency(지연 시간)를 최소화하고 싶고, 이미 소진한 페이지를 다시 읽지 않으려 하며, 실행 간에 커서를 영구 저장할 수 있는 장소가 있는 경우 |
### 윈도우 폴링
윈도우 내의 모든 활동이 이미 쿼리 가능하도록 `created_at.lt`를 현재로부터 최소 1분 이전으로 설정하세요. 연속된 윈도우가 간격이나 중복 없이 이어지도록 하한에는 `created_at.gte`를, 상한에는 `created_at.lt`를 사용하고, 이전 윈도우의 `lt` 값을 다음 윈도우의 `gte`로 재사용하세요.
```bash cURL
curl --fail-with-body -sS -G \
"https://api.anthropic.com/v1/compliance/activities" \
--header "x-api-key: $ANTHROPIC_COMPLIANCE_ACCESS_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`가 되면 중단), 더 작은 시간 윈도우를 선택하세요. 전체 계약은 [결과 페이지네이션](https://platform.claude.com/docs/ko/manage-claude/compliance-activity-feed#paginate-results)을 참조하세요.
윈도우가 깔끔하게 이어지더라도, 윈도우가 닫힌 후에 인덱싱된 활동은 이후 윈도우에 절대 나타나지 않습니다. 활동 `id`로 중복을 제거하고, 각 새 윈도우를 이전 윈도우와 몇 분 겹치도록 넓히거나 오래된 윈도우를 다시 쿼리하는 주기적 조정(reconciliation) 패스를 실행하세요.
`created_at.lt` 경계를 현재에 너무 가깝게 설정하면 늦게 인덱싱된 활동이 조용히, 그리고 영구적으로 누락됩니다. `created_at.gte`가 해당 활동을 지나 전진하면 이후 어떤 윈도우로도 복구할 수 없습니다. 1분이라는 쿼리 가능 시점 수치는 느슨한 권장 사항이 아니라 문서화된 인덱싱 지연으로 취급하세요.
### 커서 기반 증분 읽기
```bash cURL
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_COMPLIANCE_ACCESS_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`로 전달하세요. 커서와 페이지 토큰의 전체 비교 레퍼런스 및 재시도 의미 체계는 [결과 페이지네이션](https://platform.claude.com/docs/ko/manage-claude/compliance-activity-feed#paginate-results)을 참조하세요.
프로덕션 **캐치업(catch-up)** 루프는 `has_more`와 `first_id`로 반복을 구동하여 마지막 폴링 이후 기록된 활동을 가져옵니다.
```text
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)
```
커서는 키 교체 후에도 유효합니다. [키 관리 및 교체](https://platform.claude.com/docs/ko/manage-claude/compliance-api-access#manage-and-rotate-keys)를 참조하세요.
각 페이지는 전달한 커서에 인접해 있습니다. 루프는 한 번에 한 페이지씩 현재를 향해 앞으로 진행합니다. `has_more`가 `true`인 동안에는 단일 응답을 최신 상태로 간주하지 마세요. `has_more`가 `false`가 된 후에만 커서를 저장하세요. 아직 가져오지 않은 페이지는 이 응답의 `first_id`와 현재 사이에 있는 더 새로운 페이지들이며, 루프를 완료하거나 다시 실행할 때까지 읽히지 않은 상태로 남습니다.
## SIEM과 상관 분석하기
각 `Activity`에는 SIEM(Splunk, Datadog, Microsoft Sentinel, Cribl 등)에 이미 있는 이벤트와 조인할 수 있는 필드가 포함되어 있습니다.
| Compliance API 필드 | 조인 대상 |
| --------------------- | ------------------------------------- |
| `actor.user_id` | ID 공급자의 안정적인 사용자 식별자 |
| `actor.email_address` | 안정적인 ID를 사용할 수 없을 때의 디렉터리 이메일 |
| `actor.ip_address` | 네트워크, VPN, 엔드포인트 로그 |
| `actor.user_agent` | 엔드포인트 및 디바이스 인벤토리, 그리고 요청을 보낸 클라이언트 앱 |
| `created_at` | 모든 소스에 걸친 시간 윈도우 상관 분석 |
`actor.user_id`와 `actor.email_address`는 `actor.type`이 `user_actor`일 때 존재합니다. `actor.ip_address`와 `actor.user_agent`는 `anthropic_actor`, `scim_directory_sync_actor` 같은 일부 액터 유형에서는 없습니다. 이러한 필드를 읽기 전에 판별자(discriminator)를 확인하세요. `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 키에 귀속시키세요.
## 콘텐츠 보존 계획하기
나중에 조회할 수 있는 항목은 다섯 가지 보존 기간에 의해 결정됩니다.
| 데이터 | 보존 기간 | 관리 주체 |
| -------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------ |
| Activity Feed 레코드 | 6년 | Anthropic |
| 채팅, 파일 및 프로젝트 콘텐츠 | 조직의 claude.ai 보존 정책에 따름(사용자가 그 전에 삭제하는 경우 제외) | 조직 |
| 로컬 세션 트랜스크립트(사용자 컴퓨터의 세션) | 기본 6년, 조직에서 유한한 사용자 지정 대화 보존 기간을 설정한 경우 해당 기간; "HIPAA readiness"(HIPAA 준비)가 활성화된 조직에서는 30일 | 기본적으로 Anthropic, 조직에서 사용자 지정 기간을 설정한 경우 조직 |
| 원격 세션 트랜스크립트(클라우드의 세션) | 6년(사용자가 그 전에 세션을 삭제하는 경우 제외) | Anthropic |
| Compliance API를 통해 "hard-delete"(영구 삭제)된 콘텐츠 | 보존되지 않음. 삭제는 즉시 영구적으로 적용됨 | `DELETE` 엔드포인트 호출자 |
Claude Platform의 나머지 부분이 보존을 어떻게 처리하는지 알아보려면 [API 및 데이터 보존](https://platform.claude.com/docs/ko/manage-claude/api-and-data-retention)을 참조하세요.
내보내기 후 보관(export-and-archive) 방식과 온디맨드 API 조회 방식 중 다음과 같이 결정하세요.
* 활동 메타데이터나 세션 트랜스크립트에 대한 법적 보존 또는 감사 기간이 6년을 초과하는 경우, 수집하는 대로 Activity Feed 페이지와 세션 트랜스크립트를 자체 아카이브로 내보내세요.
* 콘텐츠 보존 정책이 eDiscovery 기간보다 짧은 경우, 보존 기간이 만료되기 전에 채팅 및 파일 콘텐츠를 내보내세요. Compliance API는 보존 정책에 의해 이미 제거된 콘텐츠를 반환할 수 없습니다. 로컬 세션 트랜스크립트에도 동일하게 적용되며, 유한한 사용자 지정 대화 보존 기간이 설정된 경우 해당 기간이 6년보다 짧더라도 그 기간을 따릅니다. 로컬 세션 엔드포인트는 설정이 변경되는 즉시 조직의 현재 기간보다 오래된 메시지를 반환하지 않으며, 나중에 기간을 늘려도 이미 만료된 트랜스크립트는 복원되지 않으므로, 해당 기간 이후에도 보관해야 하는 트랜스크립트는 모두 내보내세요.
* 사용자가 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 객체 이해하기](https://platform.claude.com/docs/ko/manage-claude/compliance-activity-feed#understand-the-activity-object) 참조). 채팅 메시지는 있지만 `claude_chat_viewed` 활동이 없는 기간이 있다고 해서 그 자체로 데이터 누락을 의미하지는 않습니다. 대신 순회와 [윈도우 폴링](https://platform.claude.com/docs/ko/manage-claude/compliance-integration-patterns#window-polling)에서 설명한 중복 또는 조정 패스에 의존하세요.
콘텐츠 엔드포인트(채팅, 파일, 프로젝트, 프로젝트 첨부 파일, 로컬 및 원격 세션 트랜스크립트)는 Claude Enterprise 데이터만 제공합니다. Activity Feed는 조직 전체의 관리 및 리소스 이벤트를 표시합니다. Compliance API에는 다음이 포함되지 않습니다.
* Claude Console 또는 API 키로 인증된 Claude API 워크로드의 프롬프트 텍스트나 모델 응답.
* Anthropic으로 전송되지 않는 로컬 세션의 기기 내 활동(예: Claude가 읽지 않은 로컬 파일).
* Claude Console API 키로 인증된 Claude Code 사용, 서드파티 클라우드 플랫폼(Amazon Bedrock, Google Cloud 또는 Microsoft Foundry)을 통해 실행된 Claude Code 사용, 또는 사용자 컴퓨터가 아닌 클라우드 인프라에서 실행되는 [Claude Code 클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web)에서 실행된 Claude Code 사용.
* [HIPAA 준비](https://platform.claude.com/docs/ko/manage-claude/api-and-data-retention#hipaa-readiness)가 활성화된 조직에서 Cowork 및 Claude Code 이외의 제품의 로컬 세션, 그리고 [제로 데이터 보존](https://platform.claude.com/docs/ko/manage-claude/api-and-data-retention#zero-data-retention-zdr-scope)이 적용되는 로컬 세션.
* 세션 트랜스크립트에 포함된 사고 블록, 이미지 또는 기타 바이너리 콘텐츠(트랜스크립트에는 사용자 프롬프트, 어시스턴트 응답 및 도구 활동만 포함됩니다. 로컬 세션 트랜스크립트에서는 바이너리 콘텐츠가 생략된 위치에 자리 표시자 `text` 블록이 표시됩니다).
* claude.ai가 추출된 텍스트 형태로 저장한 채팅 첨부 파일의 원본 파일(예: 일부 Word, PowerPoint 및 PDF 업로드). 이 경우 파일 콘텐츠 엔드포인트는 추출된 텍스트를 반환합니다. [파일 및 아티팩트 조회](https://platform.claude.com/docs/ko/manage-claude/compliance-content-data#retrieve-files-and-artifacts)을 참조하세요.
* 로컬 세션의 시스템 프롬프트(대신 마커 메시지가 표시됩니다).
* 세션 트랜스크립트(로컬 또는 원격)의 도구 정의 및 MCP 서버 구성, 그리고 로컬 세션 트랜스크립트의 `text` 블록에 포함된 인용 메타데이터.
* [고객 관리형 암호화 키](https://platform.claude.com/docs/ko/manage-claude/cmek)를 현재 사용할 수 없는 조직의 로컬 세션 트랜스크립트 콘텐츠. 이러한 요청은 [503 Service Unavailable](https://platform.claude.com/docs/ko/manage-claude/compliance-errors#local-sessions-temporarily-unavailable)을 반환하지만, 세션 메타데이터는 계속 목록에 표시됩니다.
* 조직의 보존 정책에 따라 제거된 콘텐츠.
* 사용자가 claude.ai에서 삭제한 채팅의 콘텐츠(채팅 자체는 `deleted_at` 값이 채워진 상태로 계속 목록에 표시됩니다).
* 사용자가 삭제한 원격 세션(삭제된 세션은 더 이상 목록에 표시되지 않으며, 메시지 엔드포인트는 해당 세션에 대해 404를 반환합니다).
* Compliance API를 통해 영구 삭제된 콘텐츠.
Compliance API가 캡처하는 것과 캡처하지 않는 것에 대한 자세한 내용은 [Compliance API FAQ](https://platform.claude.com/docs/ko/manage-claude/compliance-faq#data-coverage-and-retention)를 참조하세요.
관리 연속성(chain of custody)을 위해, 내보낸 레코드를 출처 메타데이터(소스 엔드포인트, 쿼리 매개변수, 실행 타임스탬프, 각 레코드의 콘텐츠 해시)와 함께 저장하세요.
## 다음 단계
필터 매개변수, 페이지네이션, `Activity` 객체 스키마.
영구 삭제를 포함한 채팅, 파일, 프로젝트 엔드포인트.
Cowork, Claude Code 등 Claude 앱과 에이전트에서 사용자가 실행하는 세션을 나열하고 해당 트랜스크립트를 조회합니다.