Claude Tag API로 Slack 채널 설정 관리하기: Enterprise 권한부터 설정 상속 조회까지

Slack 채널에서 Claude 설정이 예상과 다르게 적용된다면, 채널에 저장된 값과 상위 설정에서 물려받은 값을 구분해야 합니다. Claude Tag API는 Claude Enterprise 조직의 Slack 설정을 조회·변경하고, 적용된 설정의 출처를 보여줍니다. Claude Console 조직이나 Console에서 만든 키로는 사용할 수 없습니다.

이 글은 이미 Claude Tag를 설정하고 Slack을 연결한 조직에서, 채널 하나의 설정을 찾고 변경한 뒤 상속 결과를 확인하는 흐름을 다룹니다.

이 글에서 사용하는 주요 용어 정의

용어정의

Admin API 키	조직 관리 API를 호출하는 키로, Claude Tag용 권한 범위를 선택해야 합니다.
저장값	해당 채널이나 워크스페이스에 직접 지정한 설정입니다.
상속 조회	상위 설정을 반영해 실제 적용되는 값을 읽는 조회 방식입니다.
sources	응답의 각 설정이 어디에서 왔는지 나타내는 정보입니다.

1. Enterprise 키에 조회·쓰기 권한 부여하기

Anthropic의 Admin API 키 안내에 따르면, Enterprise의 primary owner가 claude.ai → Organization settings → API에서 키를 발급합니다. 일반 organization owner의 키 생성 권한은 Compliance 범위로 제한되므로, Claude Tag 키는 primary owner에게 요청해야 합니다.

필요한 권한은 작업에 따라 나뉩니다.

권한허용 작업

read:claude_tag	GET 조회
write:claude_tag	POST 설정 변경

쓰기 권한에는 읽기 권한이 포함되지 않습니다. 채널을 찾고 수정한 뒤 재조회하려면 둘 다 필요합니다. 키 생성 후 권한을 추가할 수 없으므로, 누락했다면 새 키를 발급해야 합니다. 비밀값은 한 번만 표시되며 비밀 저장소에 보관합니다.

2. Slack ID로 API의 채널 ID 찾기

Claude Tag API 가이드는 Slack 자체 ID와 API가 발급하는 ID를 구분합니다. Slack의 워크스페이스·채널 ID로 검색한 뒤, 응답의 slch_로 시작하는 채널 ID를 이후 경로에 사용합니다.

아래는 공식 문서 기반의 HTTP 요청 형식 예제이며, 실제 API 실행은 검증하지 않았습니다. <...>는 실제 값으로 바꿀 자리입니다. 모든 요청에는 다음 헤더가 필요합니다.

x-api-key: <ADMIN_API_KEY>
anthropic-version: 2023-06-01
anthropic-beta: experimental-claude-tag-2026-10-21

먼저 Slack ID 두 개를 쿼리 매개변수로 전달합니다.

GET /v1/organizations/claude_tag/slack_channels?slack_workspace_id=<SLACK_WORKSPACE_ID>&slack_channel_id=<SLACK_CHANNEL_ID>

목록에는 Claude Tag 설정 레코드가 있는 채널만 나옵니다. 결과에 없다고 Slack 채널 자체가 없다고 판단하면 안 됩니다.

3. 저장값과 실제 적용값 비교하기

찾은 채널 ID로 기본 GET을 호출하면 저장값을 읽습니다. 같은 경로에 include_inherited=true를 붙이면 상속을 반영한 적용값을 읽습니다.

GET /v1/organizations/claude_tag/slack_channels/<CHANNEL_RESOURCE_ID>

GET /v1/organizations/claude_tag/slack_channels/<CHANNEL_RESOURCE_ID>?include_inherited=true

일반적인 설정 우선순위는 채널 → 워크스페이스 → Slack defaults입니다. 다만 instructions는 넓은 범위부터 누적되며, 부모 코드채널과 Enterprise Grid에는 추가 규칙이 있습니다. 모든 설정을 단순히 “채널 값이 덮어쓴다”로 해석하면 안 됩니다.

저장값에서 null은 해당 수준에 값을 지정하지 않아 상속한다는 뜻입니다. 상속 조회에서는 값의 null 여부 대신 sources를 보고 적용 출처를 판단합니다. 상속 수준을 읽지 못하면 API는 503을 반환하므로, 이를 빈 설정으로 처리하지 않습니다.

4. 한 필드를 변경한 뒤 상속 조회로 확인하기

다음 요청은 해당 채널의 Claude Tag를 끄는 예제입니다. 공통 헤더에 Content-Type: application/json을 추가합니다.

POST /v1/organizations/claude_tag/slack_channels/<CHANNEL_RESOURCE_ID>
Content-Type: application/json

{"settings":{"enabled":false}}

settings에서 생략한 필드는 유지됩니다. 직접 지정한 값을 지우고 상속으로 돌아가려면 같은 POST 요청에 아래 본문을 보냅니다.

{"settings":{"enabled":null}}

null은 비활성화를 뜻하지 않습니다. 상위 설정에 따라 다시 켜질 수 있으므로, 변경 후에는 include_inherited=true GET으로 적용값과 sources를 함께 확인합니다. 이 옵션은 조회용이며 생성·변경 요청에 보내면 400 오류가 납니다.

운영에서 구분할 경계

Slack 연결·해제와 조직의 Slack defaults 변경은 claude.ai에서 처리합니다. API / Terraform read-only mode는 UI 수정을 제한하는 기능이므로, API 쓰기를 막는 장치로 이해하면 안 됩니다.

처음에는 채널 하나를 골라 저장값과 상속 조회 응답을 비교해 보세요. 적용 출처를 파악한 다음 필요한 필드만 변경하고 재조회하면, 상위 설정을 놓친 채 채널 설정을 덮어쓰는 실수를 줄일 수 있습니다.

참고 링크

• Anthropic — Claude Tag API
• Anthropic — Create an Admin API key