토큰 관리
토큰 관리 (Tokens Management)
조직 관리자가 조직 내 액세스 토큰을 감독해 조직 리소스에 대한 안전한 접근을 보장할 수 있게 해주는 기능이에요. Team & Enterprise 요금제에서 사용할 수 있습니다.
출처: 문서
본문
[!WARNING] 이 기능은 Team & Enterprise 요금제의 일부입니다.
Tokens Management를 사용하면 조직 관리자가 조직 내 액세스 토큰을 감독해 조직 리소스에 대한 안전한 접근을 보장할 수 있어요.
[!NOTE] 토큰 관리 정책이 적용될 때의 멤버 경험 — 토큰 상태 확인 방법, 기대할 오류, 거부·회수가 토큰에 미치는 영향 등 — 은 토큰 관리 정책이 있는 조직의 토큰을 참고하세요.
액세스 토큰 보기·관리 (Viewing and Managing Access Tokens)
토큰 목록 기능은 조직 내 모든 액세스 토큰을 표시합니다. 관리자는 다음을 할 수 있어요:
- 토큰 사용을 모니터링하고 잠재적 보안 위험을 식별·예방:
- 비공개 리소스에 대한 무단 접근("유출")
- 지나치게 광범위한 액세스 스코프
- 최적이 아닌 토큰 위생(예: 오랫동안 순환되지 않은 토큰)
- 비활성 또는 미사용 토큰 식별
Fine-grained 토큰은 특정 권한을 표시합니다:
기본적으로 회수(revoked)된 토큰은 목록에서 숨겨져 있어요. 목록 위의 Show revoked tokens 토글을 사용해 보기에 포함시킬 수 있습니다.
조직의 토큰 정책과 무관하게 회수된 토큰에는 REVOKED 상태 배지가 표시됩니다. PENDING, APPROVED, DENIED 배지는 "Require administrator approval" 정책이 활성화된 조직에서만 나타나는데, 그 상태들은 승인 흐름에 의해서만 생성되기 때문이에요.
토큰 정책 (Token Policy)
Team & Enterprise 조직 관리자는 다음 정책을 적용할 수 있어요:
| 정책 (Policy) | 스코프 없는 (읽기/쓰기) 액세스 토큰 (Unscoped (Read/Write) Access Tokens) | Fine-Grained 토큰 |
|---|---|---|
| User Access Tokens로 접근 허용 (기본값) | 승인됨 (Authorized) | 승인됨 (Authorized) |
| fine-grained 토큰으로만 접근 | 승인 안 됨 (Unauthorized) | 승인됨 (Authorized) |
| 관리자 승인 요구 (Require administrator approval) | 승인 안 됨 (Unauthorized) | 승인 없이는 승인 안 됨 (관리자 생성 제외) |
토큰 인증 검토 (Reviewing Token Authorization)
토큰 정책이 "Require administrator approval"로 설정되면 조직 관리자는 조직 소유 리소스에 접근하는 모든 fine-grained 토큰의 세부 정보를 검토하고 접근을 승인하거나 거부할 수 있어요. 새 토큰이 pending 상태에 들어가면, 이메일이 확인된 최대 50명의 조직 관리자에게 토큰 검토 페이지로 가는 직접 링크가 포함된 알림이 전송됩니다. 토큰이 자동 승인될 때(예: 생성자가 조직 관리자인 경우)에는 알림이 전송되지 않아요.
- Pending 토큰은 관리자 결정을 기다리고 있는 상태
- Approved 토큰은 승인되어 활성 상태
- Denied 토큰은 조직 리소스 접근이 차단된 상태
토큰이 승인되거나 거부되면 토큰 소유자에게 이메일 알림이 전송됩니다.
거부는 영구적이지 않아요: 거부된 토큰은 나중에 관리자가 승인해 접근을 복원할 수 있습니다. 마찬가지로 이미 승인된 토큰도 언제든 거부할 수 있으며, 승인 기반 접근이 즉시 제거됩니다.
[!NOTE] 토큰 이름은 "Require administrator approval" 정책이 활성화된 경우에만 관리자에게 표시됩니다.
차단되었을 때 멤버가 보는 것 (What Members See When Blocked)
토큰이 pending 또는 denied 상태인 멤버는 조직 리소스에 접근할 때 403 오류를 받습니다: "Due to the organization token policy, your token needs to be approved by the organization before you can access this resource."
오류 메시지는 pending과 denied 모두 동일해요. 상태를 보려면 멤버가 개별 토큰의 편집 페이지로 이동할 수 있습니다. 조직 관리자 토큰 관리 설정 페이지에는 모든 멤버 토큰의 상태 배지가 표시됩니다.
거부 vs 회수 (Deny vs. Revoke)
관리자는 토큰의 조직 접근을 제거하는 두 가지 방법이 있어요:
| 측면 (Aspect) | 거부 (Deny) | 회수 (Revoke) |
|---|---|---|
| 요금제 (Plan) | Team & Enterprise | Enterprise 요금제 이상 |
| 범위 (Scope) | 승인 워크플로 내에서 동작 | 토큰 정책과 무관 |
| 효과 (Effect) | 승인 기반 접근을 차단·제거 | 정책이나 토큰 상태와 무관하게 접근을 강제 제거 |
| 되돌릴 수 있나? | 네 — 거부된 토큰은 나중에 승인 가능 | 아니요 — 정책이 변경돼도 회수 상태 유지 |
| 다른 곳의 토큰 | 조직 밖에는 영향 없음 | 조직 밖에는 영향 없음 |
승인 워크플로 내에서 접근을 관리할 때는 거부를 사용하세요(토큰이 denied 상태로 전환되고 나중에 재승인될 수 있음). 토큰의 조직 접근을 영구적으로 차단해야 할 때는 회수를 사용합니다.
API로 토큰 목록 보기 (Listing Tokens via API)
설정 UI에 표시되는 토큰 목록은 프로그래밍 방식으로도 사용할 수 있어요:
# ORG_NAME should be your organization name and ADMIN_HF_TOKEN an admin's access token
curl -H "Authorization: Bearer ***" \
"https://huggingface.co/api/organizations/${ORG_NAME}/settings/tokens"
응답은 멤버 액세스 토큰의 배열입니다. 전체 스키마는 OpenAPI 레퍼런스를 참고하세요: GET /api/organizations//settings/tokens
기본적으로 회수된 토큰은 숨겨져 있습니다. UI의 Show revoked tokens 토글처럼 포함하려면 q=status:all을 전달하세요.
토큰 회수 (Revoking Tokens)
[!WARNING] 이 기능은 Enterprise 요금제 이상의 일부입니다.
조직 관리자는 토큰 상세 페이지에서 멤버의 액세스 토큰을 회수할 수 있어요. 회수는 조직이 "Require administrator approval" 정책을 사용하는지와 무관하게 사용할 수 있습니다. 회수된 토큰은 더 이상 조직 리소스에 접근할 수 없지만, 다른 곳에서는 계속 동작해요. 회수 시 토큰 소유자에게 이메일 알림이 전송됩니다.
회수된 토큰은 조직의 토큰 정책이 나중에 변경되거나 비활성화되어도 회수 상태를 유지합니다. 회수는 조직 수준에서 영구적이며, 회수를 취소하는 동작은 없어요. 멤버가 접근을 복원해야 한다면 회수된 토큰을 삭제하고 새로 만들어야 합니다. 조직이 "Require administrator approval" 정책을 사용한다면 새 토큰은 pending 상태에서 시작해 관리자 승인이 필요해요.
토큰이 회수된 멤버는 다음 메시지와 함께 403 오류를 받습니다: "Your token has been revoked by the organization administrator, you can no longer access organization resources. Please contact them for more information." 이 메시지는 조직이 "Require administrator approval" 정책을 사용하는지와 무관하게 표시됩니다.
API로 회수하기 (Revoking via 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 ***"
관리자는 자신의 토큰을 회수할 수 없습니다: 토큰 id가 인증에 사용된 토큰과 일치하는 요청은 403 오류로 거부됩니다.
[!NOTE] 이 엔드포인트는 토큰의 조직 접근만 회수하며, 토큰은 소유자의 다른 리소스에서는 계속 동작합니다. 유출된 토큰을 모든 곳에서 무효화하려면 인증이 필요 없고 원시 토큰 값 배치를 받는
POST /api/credentials/revoke를 대신 사용하세요.
프로그래밍 방식 토큰 발급 (Programmatic Token Issuance)
[!WARNING] 이 기능은 Enterprise 요금제 이상의 일부입니다.
멤버를 위해 액세스 토큰을 프로그래밍 방식으로 발급해야 하는 조직(예: 내부 플랫폼, CI/CD 파이프라인, 커스텀 통합)에는 OAuth Token Exchange를 참고하세요. 이 Enterprise 요금제 기능을 사용하면 백엔드 서비스가 대화형 사용자 동의 없이 조직 멤버를 위한 스코프 한정 토큰을 발급할 수 있어요.
서비스 계정 (Service Accounts)
[!WARNING] 이 기능은 Enterprise 요금제 이상의 일부입니다.
개별 멤버가 아닌 조직이 소유하는 자동화 접근을 위해, 관리자는 Service Accounts를 만들고 조직 리소스에 스코프된 fine-grained 토큰을 발급할 수 있어요.
더 알아보기 (Learn more)
Tokens Management(Team & Enterprise)는 조직의 액세스 토큰을 관리자에게 보여주고, 토큰 정책(fine-grained 전용, 관리자 승인)과 deny/revoke를 통해 접근을 제어해요. API로는 GET /api/organizations/{org}/settings/tokens로 목록을, POST .../tokens/{id}/revoke로 회수할 수 있어요. Enterprise 이상에서는 프로그래밍 토큰 발급과 Service Accounts도 사용할 수 있습니다.