Compliance API 설정

Compliance API 설정

이 페이지는 조직에 Compliance API를 활성화하고 API 키를 만드는 방법을 설명해 드릴게요.

Claude Enterprise 조직과 자격이 되는 독립 Claude Console 조직은 Compliance API에 셀프서비스로 접근할 수 있어요. 이 페이지는 조직에 Compliance API를 활성화하고 API 키를 만드는 방법을 설명해요.

필요한 역할: 조직 admin(Claude Console), 또는 primary owner·organization owner(claude.ai).

Compliance API는 두 가지 키 유형을 사용하며, 어떤 것을 만들지는 조직이 사용하는 Claude 제품에 따라 달라져요. primary owner와 organization owner는 claude.ai에서 Compliance Access Key를 만들어요. 이 키는 전체 Compliance API를 열어줘요. primary owner의 키는 상위 조직 아래의 모든 조직을 다룰 수 있고, organization owner의 키는 자신의 조직만 다뤄요. 조직 admin은 Claude Console에서 Admin API 키를 만들어요. 이 키는 Activity Feed만 열어줘요.

출처: 문서

본문

어떤 키가 필요한가요?

Claude Enterprise 테넌트는 아래의 모든 워크로드 조직에 identity·SSO·SCIM을 중앙화하는 하나의 **상위 조직(parent organization)**을 가져요. 이 워크로드 조직들이 상위 조직의 **연결 조직(linked organizations)**이에요.

Claude Enterprise 상위 조직은 Claude Console(platform.claude.com)에 나타나지 않아요. 상위 조직은 워크로드, Claude API 키, Admin API 키를 담지 않아요. Compliance Access Key는 Claude Console이 아니라 claude.ai Organization settings에서 만들어야 해요.

Compliance API 설정

설정은 한 흐름이에요: 조직에 Compliance API를 활성화한 뒤 claude.ai에서 Compliance Access Key를 만들어요. Claude Console 조직은 활성화 후 대신 Admin API 키를 만들고, Admin API 키는 Activity Feed에만 도달해요.

read:compliance_user_data를 가진 Compliance Access Key는 모든 연결 조직의 모든 채팅·파일·프로젝트·세션 기록을, primary owner가 보지 못한 콘텐츠까지 읽을 수 있어요. delete:compliance_user_data를 가진 키는 채팅·파일·프로젝트를 영구히 삭제할 수 있어요. Compliance Access Key를 프로덕션 데이터베이스 자격 증명처럼 취급하세요: 비밀 관리자에 저장하고 소스 코드나 SIEM 전달자 구성에 절대 넣지 마세요.

1. Compliance API 활성화 — Compliance API를 어디서 활성화하는지는 조직 설정에 따라 달라져요:

   • Claude Enterprise 조직: primary owner가 claude.ai > Organization settings > API에서 Compliance API를 활성화해요. 활성화는 상위 조직 수준에서 발생하며 claude.ai와 Claude Console의 모든 연결 조직으로 전파돼요.
   • 독립 Claude Console 조직: 조직 admin이 Claude Console > Settings > Security에서 Compliance API 토글을 켜요. 활성화는 자격이 되는 조직에 대해 셀프서비스이며 변경이 즉시 적용돼요. Compliance API 섹션이 보이지 않으면 admin 역할이 없거나, 조직이 상위 조직에 연결되어 있거나(Compliance API는 대신 상위 조직에서 활성화), 조직이 셀프서비스 활성화 자격이 없는 경우예요. 어떤 것이 해당하는지 확실하지 않으면 계정 팀이나 Anthropic 지원에 문의하세요.
   • 상위 조직에 연결된 Claude Console 조직: Claude Console에서 켤 것은 없어요. 상위 조직의 primary owner에게 claude.ai에서 Compliance API를 활성화해 달라고 요청하거나 계정 팀에 문의하세요.

   Compliance API를 끄면 활동 기록이 멈춰요. 조직 admin은 켤 때와 같은 Compliance API 토글로 언제든 끌 수 있어요. Compliance API가 off인 동안 조직의 활동 이벤트가 기록되지 않으므로 Activity Feed는 새 이벤트를 받지 못해요. 조직이 Access Transparency에 등록되어 있다면, Compliance API를 끄면 Access Transparency 이벤트 전달도 멈춰요. Compliance API가 off인 동안 기록되지 않은 활동은 나중에 복구할 수 없어요. Compliance API를 다시 켜면 그 시점부터 기록이 재개되고, 이미 기록된 활동은 삭제되지 않아요. Claude Enterprise 조직의 경우 claude.ai의 Compliance API 설정은 로컬 세션(사용자 기기 세션)의 기록 캡처도 좌우해요: 캡처는 Compliance API가 활성화되면 시작되고 off인 동안 멈추며, off인 동안 실행된 세션의 기록 콘텐츠는 캡처되지 않고 나중에 복구할 수 없어요.

   독립 Claude Console 조직은 Compliance Access Key가 아니라 Admin API 키를 사용해요. 활성화 후 나머지 단계를 건너뛰고 새 Admin API 키를 만들면 돼요. 나머지 단계는 Claude Enterprise 테넌트의 일부인 조직에서만 쓸 수 있는 Compliance Access Key를 프로비저닝해요.

2. 키의 범위 결정 — 키의 접근 권한은 생성 시 설정돼요. 키가 다룰 조직을 결정하세요:

   • 상위 조직용 키는 상위 조직 아래의 모든 조직에 접근할 수 있어요.
   • 단일 조직용 키는 그 조직만 접근할 수 있어요.

3. 일치하는 역할로 로그인 — claude.ai에 로그인하세요. 상위 조직의 primary owner는 어느 범위든 키를 만들 수 있어요. organization owner는 자신의 조직으로만 제한된 키를 만들 수 있어요. 다음 단계에서 설명하는 API 페이지가 보이지 않거나 키를 만들 때 준수 범위를 사용할 수 없다면, 역할이 Compliance Access Key를 만들 수 없거나 조직에 Compliance API가 아직 활성화되지 않은 거예요(첫 단계로 돌아가세요).

4. API 설정 열기 — claude.ai > Organization settings > API로 이동해 Keys 섹션을 찾으세요.

5. 키 만들기 — Create key를 클릭하고 키 이름을 정한 뒤 다음 표에서 하나 이상의 범위를 선택하세요. Create를 클릭하세요.

   범위	부여하는 것
   read:compliance_activities	Activity Feed 읽기. 상위 조직을 다루는 키는 상위 조직과 모든 연결 조직의 이벤트를 읽어요.
   read:compliance_user_data	사용자 채팅, 메시지, 파일, 프로젝트, 세션 메타데이터·기록, 조직 사용자, 그룹 구성원 읽기
   delete:compliance_user_data	사용자 채팅, 파일, 프로젝트 삭제
   read:compliance_org_data	조직 메타데이터(이름, 유형, 역할, 그룹)와 상위 조직 아래 조직에 적용되는 유효 설정 읽기. 사용자 목록과 그룹 구성원은 read:compliance_user_data가 필요해요.

   통합이 필요로 하는 가장 작은 범위 집합을 선택하세요:

   • Activity Feed만 읽는 감사 파이프라인은 read:compliance_activities만 필요해요.
   • 채팅·파일을 읽지만 절대 삭제하지 않는 eDiscovery 도구는 delete:compliance_user_data가 필요 없어요.
   • 워크플로가 읽기와 삭제를 모두 한다면 범위가 분리된 두 개의 키를 사용해 유출된 읽기 키가 데이터를 삭제할 수 없게 하세요.

   Compliance Access Key 범위는 생성 후 변경할 수 없어요. 범위를 바꾸려면 원하는 범위로 새 키를 만들고 이전 키를 삭제하세요.

6. 비밀 복사·저장 — 표시된 비밀 키(sk-...로 시작)를 복사해 비밀 관리자에 저장하세요. 전체 비밀은 한 번만 표시돼요.

7. 가이드의 예시를 위해 키 내보내기 — 셸 샘플이 읽을 수 있도록 키를 환경 변수로 설정하세요:

   export ANTHROPIC_COMPLIANCE_ACCESS_KEY=sk-...
   

Admin API 키 만들기

Admin API 키가 Activity Feed를 호출할 수 있으려면 Claude Console 조직에 Compliance API가 이미 활성화되어 있어야 해요.

Admin API 키 만들기의 단계를 따른 뒤 키를 환경 변수로 설정하세요:

export ANTHROPIC_ADMIN_KEY=sk-...

별도의 변수 이름은 둘 다 프로비저닝할 때 Admin API 키가 Compliance Access Key를 덮어쓰지 않게 해줘요. 이 가이드의 cURL 예시는 $ANTHROPIC_COMPLIANCE_ACCESS_KEY에서 키를 읽어요. Admin API 키로 Activity Feed를 호출할 때는 $ANTHROPIC_ADMIN_KEY로 바꾸세요.

Admin API 키는 키 생성 시 조직에 Compliance API가 활성화된 경우에만 read:compliance_activities 범위를 가져요. Compliance API 설정 참고. 다른 Compliance API 범위는 부여할 수 없으므로 Activity Feed 외의 어떤 엔드포인트 호출도 403 Forbidden을 반환해요.

같은 키가 Claude Console 조직 관리에서 하는 역할은 Admin API를 참고하세요.

키의 범위 확인

보유한 키의 범위를 검사하려면 다음 신호 중 하나를 사용하세요.

• 키 접두사. sk-ant-admin...은 Admin API 키(앞선 섹션의 활성화 시점에 따라 read:compliance_activities만 가짐). sk-ant-compliance... 또는 claude.ai에서 만든 키는 Compliance Access Key이며, 범위는 생성 시 선택한 부분집합이에요.
• 설정 UI. claude.ai > Organization settings > API의 Keys 섹션 또는 Claude Console > Settings > Admin keys의 Admin keys 섹션을 열고 키의 Scopes 열을 읽으세요.
• 오류 응답. 키의 범위를 초과하는 호출은 Missing required scopes. Got: [<키가 가진 범위>] Needed one of: [<엔드포인트가 허용하는 범위>] 형식의 메시지와 함께 403을 반환해요(삭제 엔드포인트는 Needed: [...]). 전체 오류 카탈로그는 Compliance API 오류 처리 참고.

{
  "error": {
    "type": "permission_error",
    "message": "Missing required scopes. Got: ['read:compliance_activities'] Needed one of: ['read:compliance_user_data', 'read:org_audit']"
  }
}

키 관리 및 교체

Compliance Access Key를 만든 곳과 같은 Keys 표에서 삭제하세요: claude.ai > Organization settings > API로 이동. Admin API 키는 Claude Console > Settings > Admin keys에서 삭제하세요.

키 삭제는 다음 요청부터 적용돼요. 유예 기간이 없어요. Compliance Access Key는 자체적으로 만료되지 않아요.

중단 없이 키를 교체하려면:

1. 같은 범위로 새 키를 만드세요.
2. 통합이 새 키를 사용하도록 업데이트하세요.
3. 새 키로 통합이 성공하는지 확인하세요.
4. 이전 키를 삭제하세요.

교체 전에 저장된 페이지네이션 커서는 유효하게 남아 있어요. 커서는 키가 아니라 조직으로 범위가 지정돼요.

Compliance Access Key가 유출되면 즉시 삭제하고, 손상된 키가 수행한 compliance_api_accessed 활동에 대해 Activity Feed를 감사하며, 유출된 키가 도달할 수 있는 다운스트림 자격 증명을 교체하세요. 조회 범위를 지정하려면 activity_types[]=compliance_api_accessed를 전달한 뒤 클라이언트에서 actor.type이 api_actor이고 actor.api_key_id가 손상된 키와 일치하는 활동을 유지하세요. actor 스키마는 Activity 객체 이해하기를 참고하세요.

다음 단계

• 활동 피드 조회 — 이동 — read:compliance_activities를 가진 어떤 키로든 조직 전반 활동 이벤트를 읽으세요.
• 채팅·파일·프로젝트 조회 및 삭제 — 이동 — read:compliance_user_data를 가진 Compliance Access Key로 claude.ai 채팅·파일·프로젝트를 조회하고 delete:compliance_user_data로 삭제하세요.
• 세션 기록 조회 — 이동 — read:compliance_user_data를 가진 Compliance Access Key로 사용자가 Cowork·Claude Code 같은 Claude 앱·에이전트에서 실행한 세션을 나열하고 기록을 조회하세요.

더 알아보기 (Learn more)

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