토큰 관리

이 기능은 Team & Enterprise 플랜의 일부입니다.

Tokens Management을 통해 조직 관리자는 조직 내 액세스 토큰을 관리하여 조직 리소스에 대한 안전한 액세스를 보장할 수 있습니다.

토큰 관리 정책이 적용된 환경에서의 멤버 경험 — 토큰 상태 확인 방법, 예상되는 오류, 거부 및 폐기가 토큰에 미치는 영향 — 에 대해서는 토큰 관리 정책이 적용된 조직의 토큰을 참고하세요.

액세스 토큰 보기 및 관리

토큰 목록 기능은 조직 내 모든 액세스 토큰을 표시합니다. 관리자는 다음을 수행할 수 있습니다:

• 토큰 사용량을 모니터링하고 잠재적인 보안 위험을 식별하거나 방지합니다:
  • 비공개 리소스에 대한 무단 액세스(“누수”)
  • 너무 광범위한 액세스 범위
  • 부적절한 토큰 관리(예: 오랫동안 회전되지 않은 토큰)
• 비활성 또는 미사용 토큰 식별

세부 권한이 있는 토큰은 해당 권한을 표시합니다:

취소된 토큰은 기본적으로 목록에서 숨겨집니다. 목록 위의 취소된 토큰 표시 토글을 사용하여 뷰에 포함하세요.

조직의 토큰 정책과 관계없이, 폐기된 토큰에는 모두 REVOKED 상태 배지가 표시됩니다. PENDING, APPROVED, DENIED 배지는 “관리자 승인 필요” 정책이 활성화된 조직에서만 나타나며, 해당 상태는 승인 플로우에 의해 생성되기 때문입니다.

토큰 정책

Team & Enterprise 조직 관리자는 다음 정책을 적용할 수 있습니다:

토큰 인증 검토

토큰 정책이 “Require administrator approval”로 설정되어 있으면, 조직 관리자는 조직 소유 리소스에 액세스하는 모든 세부 권한 토큰의 세부 정보를 검토하고 액세스를 승인하거나 거부할 수 있습니다. 새 토큰이 대기 상태가 되면, 확인된 이메일 주소를 가진 최대 50명의 조직 관리자에게 토큰 검토 페이지로 바로 이동할 수 있는 링크가 포함된 알림이 전송됩니다. 토큰이 자동 승인되는 경우(예: 생성자가 조직 관리자임)에는 알림이 전송되지 않습니다.

• Pending 토큰은 관리자의 결정을 기다리고 있습니다
• 승인됨 토큰은 권한이 부여되어 활성 상태입니다
• Denied 토큰은 조직 리소스에 대한 액세스가 차단되었습니다

토큰이 승인되거나 거부되면 토큰 소유자에게 이메일 알림이 전송됩니다.

거부는 영구적이지 않습니다: 거부된 토큰은 나중에 관리자에 의해 승인되어 접근 권한이 복원될 수 있습니다. 마찬가지로, 이미 승인된 토큰은 언제든지 거부될 수 있으며, 이는 승인 기반 접근 권한을 즉시 제거합니다.

“관리자 승인 필요” 정책이 활성화된 경우에만 관리자에게 토큰 이름이 표시됩니다.

차단된 멤버가 보는 화면

토큰이 대기 중이거나 거부된 멤버는 조직 리소스에 액세스할 때 403 오류를 수신합니다: “조직 토큰 정책에 따라, 이 리소스에 액세스하려면 조직의 토큰 승인이 필요합니다.”

<pending> 상태와 <denied> 상태 모두에서 오류 메시지는 동일합니다. 상태를 확인하려면 구성원이 개별 토큰의 편집 페이지로 이동할 수 있습니다. 조직 관리자의 토큰 관리 설정 페이지에는 모든 구성원 토큰의 상태 배지가 표시됩니다.

Deny와 Revoke

관리자는 조직에 대한 토큰의 액세스를 제거하는 두 가지 방법을 사용할 수 있습니다:

승인 워크플로우 내에서 액세스를 관리할 때는 deny를 사용하세요(토큰은 denied 상태로 전환되며 나중에 다시 승인될 수 있습니다). 토큰의 조직 액세스를 영구적으로 차단해야 하는 경우에는 revoke를 사용하세요.

API를 통한 토큰 나열

설정 UI에 표시되는 토큰 목록은 프로그래매틱으로도 사용할 수 있습니다:

# ORG_NAME should be your organization name and ADMIN_HF_TOKEN an admin's access token
curl -H "Authorization: Bearer ${ADMIN_HF_TOKEN}" \
  "https://huggingface.co/api/organizations/${ORG_NAME}/settings/tokens"

응답은 멤버 액세스 토큰의 배열입니다. 전체 스키마는 OpenAPI 참조를 확인하세요: GET /api/organizations/<name>/settings/tokens

기본적으로 폐기된 토큰은 숨겨집니다. UI의 폐기된 토큰 표시 토글과 마찬가지로 q=status:all를 전달하면 폐기된 토큰도 포함됩니다.

토큰 폐기

이 기능은 Enterprise 플랜 이상에서 제공됩니다.

Organization 관리자는 토큰 상세 페이지에서 모든 멤버의 액세스 토큰을 취소할 수 있습니다. 조직이 “Require administrator approval” 정책을 사용하는지와 관계없이 취소가 가능합니다. 취소된 토큰은 더 이상 조직의 리소스에 액세스할 수 없지만, 다른 곳에서는 계속 작동합니다. 토큰 소유자는 취소 시 이메일 알림을 받습니다.

취소된 토큰은 조직의 토큰 정책이 나중에 변경되거나 비활성화되더라도 취소된 상태로 유지됩니다. 취소는 조직 수준에서 영구적이며, 취소 해제(un-revoke) 작업은 존재하지 않습니다. 멤버가 액세스를 복원하려면 취소된 토큰을 삭제하고 새 토큰을 생성해야 합니다. 조직이 “관리자 승인 필요” 정책을 사용하는 경우, 새 토큰은 대기(pending) 상태로 시작되며 관리자 승인이 필요합니다.

토큰이 폐기된 멤버는 403 오류와 함께 다음 메시지를 수신합니다: “조직 관리자에 의해 토큰이 폐기되었습니다. 더 이상 조직 리소스에 액세스할 수 없습니다. 자세한 내용은 관리자에게 문의하세요.” 이 메시지는 조직이 “관리자 승인 필요” 정책을 사용하는지와 관계없이 표시됩니다.

API를 통한 취소

관리자는 토큰 ID를 사용하여 토큰을 프로그래밍 방식으로 취소할 수도 있습니다. 이는 토큰을 즉시 취소해야 하는 자동화 워크플로에서 유용합니다.

# ORG_NAME should be your organization name and ADMIN_HF_TOKEN an admin's access token
# TOKEN_ID is the 24-character id shown on the org token settings page (or returned by the tokens listing API)
curl -X POST "https://huggingface.co/api/organizations/${ORG_NAME}/settings/tokens/${TOKEN_ID}/revoke" \
  -H "Authorization: Bearer ${ADMIN_HF_TOKEN}"

관리자는 자신의 토큰을 취소할 수 없습니다. 인증에 사용된 토큰과 토큰 ID가 일치하는 요청은 403 오류로 거부됩니다.

이 엔드포인트는 토큰의 조직 접근 권한만 취소하며, 토큰은 소유자의 다른 리소스에 대해서는 계속 작동합니다. 유출된 토큰을 모든 곳에서 무효화하려면 인증이 필요하지 않고 원시 토큰 값의 배치(batch)를 받아 처리하는 POST /api/credentials/revoke를 대신 사용하세요.

프로그램 기반 토큰 발급

이 기능은 Enterprise 플랜 이상에서 제공됩니다.

조직 구성원에게 액세스 토큰을 프로그래매틱으로 발급해야 하는 조직(예: 내부 플랫폼, CI/CD 파이프라인, 또는 커스텀 통합)의 경우 OAuth Token Exchange를 참조하세요. 이 Enterprise 플랜 기능은 백엔드 서비스가 조직 구성원을 위한 스코프된 토큰을 발급할 때 인터랙티브한 사용자 동의가 필요하지 않도록 합니다.

서비스 계정

이 기능은 Enterprise 플랜 이상에서 제공됩니다.

개별 멤버가 아닌 조직이 소유한 자동화된 액세스를 위해, 관리자는 Service Accounts를 생성하고 조직의 리소스에 범위가 설정된 세밀한 토큰을 발급할 수 있습니다.