# 사용자 액세스 토큰

## User Access Tokens이란 무엇인가요?

User Access Tokens는 Hugging Face 서비스에 애플리케이션 또는 노트북을 인증하는 권장 방법입니다. [설정](https://huggingface.co/settings/tokens)에서 액세스 토큰을 관리할 수 있습니다.

액세스 토큰은 애플리케이션과 노트북이 다음에 표시된 역할의 범위로 지정된 특정 작업을 수행할 수 있도록 합니다:

- `fine-grained`: 이 역할의 토큰은 특정 모델이나 특정 조직의 모델과 같은 특정 리소스에 대한 세밀한 접근을 제공하기 위해 사용할 수 있습니다. 이 유형의 토큰은 모든 리소스에 대한 접근 권한을 공유하지 않고도 자체 토큰을 사용할 수 있으므로 프로덕션 환경에서 유용합니다.

- `read`: 이 역할을 가진 토큰은 읽을 수 있는 저장소에 대한 읽기 전용 액세스를 제공하는 데만 사용할 수 있습니다. 여기에는 사용자가 소유한 공개 및 비공개 저장소, 또는 사용자가 소속된 조직이 소유한 저장소가 포함됩니다. Hugging Face Hub에서 콘텐츠 읽기만 필요한 경우(예: 비공개 모델 다운로드 또는 추론 수행 시) 이 역할을 사용하세요.

- `write`: 이 역할을 가진 토큰은 쓰기 권한이 있는 저장소에 대한 쓰기 접근 권한을 추가로 부여합니다. 저장소에 콘텐츠를 생성하거나 푸시해야 하는 경우(예: 모델 학습 또는 모델 카드 수정 시) 이 토큰을 사용하세요.

조직의 읽기/쓰기/관리자(read/write/admin) 역할 멤버인 경우, 사용자 액세스 토큰(User Access Tokens)은 토큰 권한(read/write) 및 조직 멤버십(read/write/admin)에 따라 리소스를 읽기/쓰기할 수 있습니다.

## User Access Tokens를 관리하는 방법

액세스 토큰을 생성하려면 설정으로 이동한 후 [Access Tokens 탭](https://huggingface.co/settings/tokens)을 클릭하세요. **New token** 버튼을 클릭하여 새로운 User Access Token을 생성합니다.

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

**Manage** 버튼을 클릭하여 User Access Tokens를 삭제하고 새로고침할 수 있습니다.

## User Access Tokens를 사용하는 방법

User Access Token을 사용하여 Hugging Face Hub에 액세스하는 방법은 다양하며, 이를 기반으로 훌륭한 앱을 구축하는 데 필요한 유연성을 제공합니다.

User Access Tokens은 다음과 같습니다:

- git 또는 기본 인증을 통해 Hugging Face Hub에 액세스할 때 **비밀번호 대신** 사용
- [Inference Providers](https://huggingface.co/docs/inference-providers)를 호출할 때 **bearer token**으로 전달됩니다.
- `transformers`나 `datasets`와 같은 Hugging Face Python 라이브러리에서 사용됩니다:

```python
from transformers import AutoModel

access_token = "hf_..."

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

> [!WARNING]
> 토큰이 유출되지 않도록 주의하세요! 토큰은 언제든 재발급할 수 있지만, 그 사이에는 누구나 사용자의 비공개 저장소를 읽거나 쓸 수 있으며 이는 💩입니다. 토큰이 노출된 경우 [유출된 토큰 폐기](#revoking-a-leaked-token)를 참고하세요.

### 최적의 관행

각 앱 또는 용도별로 액세스 토큰을 하나씩 생성하는 것을 권장합니다. 예를 들어, 다음 용도별로 별도의 토큰을 사용할 수 있습니다:

- 로컬 머신
- Colab 노트북입니다.
- 훌륭한 사용자 정의 추론 서버입니다.

이렇게 하면 다른 사용에 영향을 주지 않고 하나의 토큰만 무효화할 수 있습니다.

프로덕션 환경에서는 세밀한 권한을 가진 토큰만 사용하는 것을 권장합니다. 유출 시 영향 범위가 줄어들며, 계정에 영향을 주지 않고 조직 내에서 공유할 수 있습니다.

예를 들어, 프로덕션 애플리케이션이 게이트된 모델에 대한 읽기 접근 권한이 필요한 경우, 조직의 구성원이 해당 모델에 대한 접근을 요청한 후, 그 모델에 대한 읽기 접근 권한이 있는 세밀한 토큰을 생성할 수 있습니다. 이 토큰은 프로덕션 애플리케이션에서 사용될 수 있으며, 이를 통해 모든 비공개 모델에 대한 접근 권한을 부여하지 않아도 됩니다.

### CI/CD 파이프라인을 위한

CI/CD 워크플로(GitHub Actions, GitLab CI, CircleCI, …)에서만 액세스가 필요한 경우, CI 시크릿으로 액세스 토큰을 저장하는 것을 완전히 생략할 수 있습니다. 각 실행 시작 시 CI 제공자의 OpenID Connect(OIDC) ID 토큰을 짧은 수명의 Hub 토큰으로 교환하는 [Trusted Publishers](./trusted-publishers)를 참조하세요. 이는 레포지토리 범위(모델, 데이터셋, Spaces 또는 커널을 게시하거나 읽기 전용으로 가져오기 위해) 또는 사용자 범위(액세스 권한이 있는 게이트드 레포지토리를 읽고 계정의 속도 제한을 확인하기 위해)로 설정할 수 있습니다.

### Enterprise 조직을 위한

조직에서 각 사용자가 개별 토큰을 생성하지 않고도 멤버를 위해 토큰을 프로그래매틱으로 발급해야 하는 경우, [OAuth Token Exchange](./oauth#token-exchange-for-organizations-rfc-8693)를 참조하세요. 이 Enterprise 플랜 기능은 조직 멤버를 대신하여 Hugging Face 리소스에 접근해야 하는 내부 플랫폼, CI/CD 파이프라인 또는 커스텀 통합을 구축하는 데 이상적입니다.

## 누출된 토큰 폐기

사용자 소유의 토큰 중 하나가 유출된 경우, 설정의 [Access Tokens 탭](https://huggingface.co/settings/tokens)에서 해당 토큰을 삭제하거나 새로고침하세요.

다른 사람의 Hugging Face 액세스 토큰을 발견한 경우, [`POST /api/credentials/revoke`](https://huggingface-openapi.hf.space/#tag/tokens/POST/api/credentials/revoke) 엔드포인트를 사용하여 이를 무효화할 수 있습니다. 토큰을 소유한 계정 또는 조직에 대한 권한이 필요하지 않습니다.

```bash
# 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` 배열에 여러 토큰 값을 한 번의 호출로 전달할 수 있으며, 이는 배치로 결과를 보고하는 시크릿 스캐닝 파이프라인에 유용합니다.

제출된 모든 토큰 중 기존 토큰과 일치하는 토큰은 즉시 무효화되어 모든 곳에서 작동이 중단됩니다. 이는 [조직 수준 폐기](./enterprise-tokens-management#revoking-via-api)와 달리 단일 조직에 대한 토큰의 접근만 차단하는 것과 다릅니다. 토큰 소유자는 이메일로 통지를 받으며, 접근을 복구하려면 새 토큰을 생성해야 합니다.

이 엔드포인트는 제출한 토큰이 존재했는지 여부와 관계없이 항상 `202 Accepted`로 응답하므로, 응답을 사용하여 토큰이 유효한지 확인하는 데 사용할 수 없습니다. 동일한 토큰을 다시 제출해도 해롭지 않습니다. 반복 호출은 아무 효과도 없으며 소유자에게는 한 번만 알림이 전송됩니다.

> [!TIP]
> 셸 히스토리나 로그에 토큰 값이 노출되지 않도록 환경 변수나 파일을 통해 전달하고, 원시 토큰을 명령줄에 직접 붙여 넣지 마세요.

## 토큰 관리 정책이 있는 조직의 토큰

Team 및 Enterprise 플랜의 조직은 해당 조직의 리소스에 액세스할 때 토큰의 작동 방식에 영향을 미치는 토큰 정책을 적용할 수 있습니다.

### 토큰이 승인(팀 및 엔터프라이즈 조직)을 필요로 하는 경우

관리자 승인이 필요한 조직에 범위가 지정된 세밀한 토큰을 생성하면, 해당 토큰은 자동으로 **Pending** 상태로 전환됩니다. 관리자가 승인하기 전까지는 해당 조직의 리소스에 접근할 수 없습니다. 토큰이 승인되거나 거부되면 이메일 알림을 받게 됩니다.

토큰 목록 페이지에서 상태를 확인할 수 있습니다. 대기 중인 토큰은 권한 배지 옆에 주황색 모래시계 아이콘이 표시되고, 거부되거나 폐기된 토큰은 빨간색 느낌표 아이콘이 표시됩니다. 토큰이 거부되거나 폐기된 경우 해당 토큰의 편집 페이지에도 빨간색 오류 배너가 표시됩니다.

> [!NOTE]
> 조직의 관리자라면, 해당 조직 범위로 설정하여 생성한 fine-grained token은 자동으로 승인되며 검토 단계가 필요하지 않습니다.

### 토큰이 거부된 경우 (Team & Enterprise 조직)

토큰이 거부되면 이메일 알림을 받게 됩니다. 토큰은 계정에 유지되며 조직 외부의 리소스에 여전히 사용할 수 있습니다. 거부된 토큰은 나중에 관리자가 승인하여 새 토큰을 생성하지 않고도 액세스를 복원할 수 있습니다.

거부된 토큰을 조직 리소스에 사용하려고 하면 `403` 오류가 발생합니다.

### 토큰이 폐기된 경우(Enterprise 조직)

취소는 영구적입니다. 거부와 달리, 취소된 토큰은 복원할 수 없습니다. 토큰이 취소된 경우, 해당 토큰을 삭제하고 새 토큰을 생성해야 합니다. 조직에서 관리자 승인을 요구하는 경우, 새 토큰은 대기 상태로 시작됩니다.

조직 리소스에 대해 취소된 토큰을 사용하려고 하면 _"조직 관리자에 의해 토큰이 취소되었습니다. 더 이상 조직 리소스에 액세스할 수 없습니다. 자세한 내용은 관리자에게 문의해 주세요."_ 메시지와 함께 `403` 오류가 반환됩니다.

취소는 해당 토큰을 취소한 조직에만 영향을 미칩니다. 토큰은 스코프가 설정된 모든 다른 리소스에 대해 정상적으로 계속 작동합니다.

### 조직이 세분화된 토큰만 허용하는 경우 (Team & Enterprise 조직)

조직에서 세밀한 권한을 가진 토큰을 요구하는 정책을 설정한 경우, 읽기/쓰기 토큰은 해당 조직의 리소스에 사용될 때 `403` 오류로 거부됩니다.