사용자 액세스 토큰

사용자 액세스 토큰 (User access tokens)

User Access Token은 애플리케이션이나 노트북을 Hugging Face 서비스에 인증하는 가장 권장되는 방법이에요. 토큰 역할(스코프)에 따라 저장소에 대한 읽기·쓰기 권한을 부여할 수 있습니다.

출처: 문서

본문

User Access Token이란 무엇인가요? (What are User Access Tokens?)

User Access Token은 애플리케이션이나 노트북을 Hugging Face 서비스에 인증하는 가장 권장되는 방법입니다. settings에서 액세스 토큰을 관리할 수 있어요.

액세스 토큰은 아래 역할의 스코프로 지정된 특정 작업을 애플리케이션·노트북이 수행할 수 있게 합니다:

  • fine-grained: 이 역할의 토큰은 특정 리소스(예: 특정 조직의 특정 모델 또는 모델들)에 대한 세밀한 접근을 제공하는 데 사용할 수 있어요. 이 유형의 토큰은 모든 리소스에 대한 접근을 공유하지 않고 내 토큰만 사용할 수 있어서 프로덕션 환경에서 유용합니다.

  • read: 이 역할의 토큰은 내가 읽을 수 있는 저장소에 대한 읽기 접근만 제공할 수 있어요. 여기에는 내가 또는 내가 멤버인 조직이 소유한 공개·비공개 저장소가 포함됩니다. Hugging Face Hub에서 콘텐츠를 읽기만 하면 될 때(예: 비공개 모델 다운로드 또는 추론) 이 역할을 사용하세요.

  • write: 이 역할의 토큰은 추가로 내가 쓰기 권한을 가진 저장소에 대한 쓰기 접근을 부여해요. 저장소에 콘텐츠를 만들거나 푸시해야 할 때(예: 모델 학습 또는 모델 카드 수정) 이 토큰을 사용하세요.

조직에서 read/write/admin 역할의 멤버라면, 내 User Access Token은 토큰 권한(read/write)과 조직 멤버십(read/write/admin)에 따라 리소스를 읽고/쓸 수 있어요.

User Access Token을 어떻게 관리하나요? (How to manage User Access Tokens?)

액세스 토큰을 만들려면 settings로 간 뒤 Access Tokens 탭을 클릭하세요. New token 버튼을 클릭해 새 User Access Token을 만들면 됩니다.

토큰의 역할과 이름을 선택하면 준비 완료!

Manage 버튼을 클릭해 User Access Token을 삭제하고 갱신할 수 있어요.

User Access Token을 어떻게 사용하나요? (How to use User Access Tokens?)

User Access Token을 사용해 Hugging Face Hub에 접근하는 방법은 많아서, 그 위에 멋진 앱을 만들기 위한 유연성을 제공합니다.

User Access Token은 다음과 같이 사용할 수 있어요:

  • git 또는 basic authentication으로 Hugging Face Hub에 접근할 때 비밀번호 대신 사용.
  • Inference Providers 호출 시 bearer 토큰으로 전달.
  • transformers나 datasets 같은 Hugging Face Python 라이브러리에서 사용:
from transformers import AutoModel

access_token = "hf_..."

model = AutoModel.from_pretrained("private/model", token=access_token)

[!WARNING] 토큰을 유출하지 않도록 주의하세요! 언제든 순환할 수는 있지만, 그 사이에 누구든 내 비공개 저장소를 읽거나 쓸 수 있게 됩니다. 토큰이 노출되었다면 유출된 토큰 회수하기를 참고하세요.

모범 사례 (Best practices)

앱 또는 용도마다 액세스 토큰 하나씩 만들 것을 권장해요. 예를 들어 다음과 같은 용도로 별도의 토큰을 가질 수 있습니다:

  • 로컬 머신.
  • Colab 노트북.
  • 멋진 커스텀 추론 서버.

이렇게 하면 다른 사용처에 영향 없이 토큰 하나를 무효화할 수 있어요.

또한 프로덕션 사용에는 fine-grained 토큰만 사용할 것을 권장합니다. 유출되더라도 영향이 줄어들고, 내 계정에 영향 없이 조직 내에서 공유할 수 있어요.

예를 들어 프로덕션 앱이 게이트된 모델에 대한 읽기 접근이 필요하다면, 조직 멤버가 그 모델에 대한 접근을 요청한 뒤 그 모델에 대한 읽기 접근이 있는 fine-grained 토큰을 만들 수 있습니다. 이 토큰은 모든 비공개 모델에 대한 접근을 주지 않고도 프로덕션 앱에서 사용할 수 있어요.

CI/CD 파이프라인용 (For CI/CD pipelines)

CI/CD 워크플로(GitHub Actions, GitLab CI, CircleCI 등)에서만 접근이 필요하다면 액세스 토큰을 CI 시크릿으로 저장하는 것을 완전히 피할 수 있어요. Trusted Publishers를 참고하세요. 이것은 매 실행 시작 시에 CI 제공자의 OpenID Connect(OIDC) 정체성 토큰을 단기 유효한 Hub 토큰으로 교환합니다 — 저장소 한정(모델, 데이터셋, Space 또는 kernel 퍼블리시용) 또는 사용자 한정(액세스 권한이 있는 게이트된 저장소 읽기와 내 계정 요율 한도 받기) 중 하나로요.

Enterprise 조직용 (For Enterprise organizations)

조직이 각 사용자가 직접 토큰을 만들게 하지 않고 멤버를 위해 토큰을 프로그래밍 방식으로 발급해야 한다면 OAuth Token Exchange를 참고하세요. 이 Enterprise 요금제 기능은 조직 멤버를 대신해 Hugging Face 리소스에 접근해야 하는 내부 플랫폼, CI/CD 파이프라인, 커스텀 통합을 구축하는 데 이상적입니다.

유출된 토큰 회수하기 (Revoking a leaked token)

내 토큰 중 하나가 유출되었다면, settings의 Access Tokens 탭에서 삭제하거나 갱신하세요.

다른 사람의 Hugging Face 액세스 토큰을 발견했다면 POST /api/credentials/revoke 엔드포인트로 무효화할 수 있어요. 토큰을 소유한 계정이나 조직에 대한 어떤 권한도 필요하지 않습니다.

# LEAKED_HF_TOKEN should contain the raw token value to revoke
curl -X POST "https://huggingface.co/api/credentials/revoke" \
  -H "Content-Type: application/json" \
  -d "{\"credentials\": [\"${LEAKED_HF_TOKEN}\"]}"

단일 호출에서 credentials 배열에 여러 토큰 값을 전달할 수 있으며, 이는 발견 사항을 배치로 보고하는 시크릿 스캐닝 파이프라인에 편리해요.

제출된 토큰 중 기존 토큰과 일치하는 것은 즉시 무효화되어 모든 곳에서 동작을 멈춥니다 — 단일 조직에 대한 접근만 차단하는 조직 수준 회수와는 달라요. 토큰 소유자에게는 이메일로 알림이 가고, 접근을 복원하려면 새 토큰을 만들어야 합니다.

이 엔드포인트는 제출된 토큰 중 기존 토큰이 있든 없든 항상 202 Accepted로 응답하므로, 응답으로 토큰 유효성을 알아낼 수 없어요. 같은 토큰을 다시 제출해도 무해합니다: 반복 호출은 아무 일도 하지 않고 소유자는 한 번만 알림을 받아요.

[!TIP] 셸 히스토리나 로그에 토큰 값이 유출되지 않도록, 환경 변수나 파일로 전달하고 원시 토큰을 커맨드라인에 직접 붙여넣는 것을 피하세요.

토큰 관리 정책이 있는 조직의 토큰 (Tokens in organizations with token management policies)

Team 및 Enterprise 요금제 조직은 그 조직의 리소스에 접근할 때 내 토큰이 어떻게 동작하는지에 영향을 주는 토큰 정책을 적용할 수 있어요.

토큰에 승인이 필요할 때 (Team & Enterprise 조직) (When your token requires approval)

관리자 승인을 요구하는 조직에 스코프된 fine-grained 토큰을 만들면, 토큰이 자동으로 Pending 상태가 됩니다. 관리자가 승인하기 전까지 그 조직의 리소스에 접근할 수 없어요. 토큰이 승인되거나 거부되면 이메일 알림을 받습니다.

토큰 목록 페이지에서 상태를 확인할 수 있는데, pending 토큰은 권한 배지 옆에 주황색 모래시계 아이콘이 표시되고, 거부되거나 회수된 토큰은 빨간 느낌표 아이콘이 표시됩니다. 토큰이 거부되거나 회수되면 토큰 편집 페이지에도 빨간 오류 배너가 나타나요.

[!NOTE] 조직의 관리자라면, 그 조직에 스코프된 fine-grained 토큰은 자동으로 승인됩니다 — 검토 단계가 필요 없어요.

토큰이 거부되었을 때 (Team & Enterprise 조직) (When your token is denied)

토큰이 거부되면 이메일 알림을 받아요. 토큰은 내 계정에 남아 있고 조직 외부 리소스에는 계속 사용할 수 있습니다. 거부된 토큰은 나중에 관리자가 승인해 새 토큰을 만들지 않고도 접근을 복원할 수 있어요.

거부된 토큰을 조직 리소스에 사용하려 하면 403 오류를 받습니다.

토큰이 회수되었을 때 (Enterprise 조직) (When your token is revoked)

회수는 영구적입니다. 거부와 달리 회수된 토큰은 복원할 수 없어요. 토큰이 회수되었다면 삭제하고 새로 만들어야 합니다. 조직이 관리자 승인을 요구한다면 새 토큰은 pending 상태에서 시작합니다.

회수된 토큰을 조직 리소스에 사용하려 하면 다음 메시지와 함께 403 오류를 받습니다: "Your token has been revoked by the organization administrator, you can no longer access organization resources. Please contact them for more information."

회수는 그 조직에만 영향을 줍니다. 토큰은 스코프된 다른 모든 리소스에서는 정상적으로 계속 동작해요.

조직이 fine-grained 토큰만 허용할 때 (Team & Enterprise 조직) (When your organization only allows fine-grained tokens)

조직이 fine-grained 토큰을 요구하는 정책을 설정했다면, read/write 토큰은 그 조직의 리소스에 사용될 때 403 오류로 거부됩니다.

더 알아보기 (Learn more)

User Access Token은 fine-grained/read/write 세 역할로 나뉘며, settings의 Access Tokens 탭에서 만들고 관리해요. 비밀번호 대신, bearer 토큰으로, 또는 transformers·datasets에 token 인자로 사용할 수 있고, 프로덕션에는 fine-grained 토큰을 권장해요. 유출된 토큰은 POST /api/credentials/revoke로 무효화할 수 있습니다.