Token akses pengguna

Apa itu User Access Tokens?

User Access Tokens adalah cara yang direkomendasikan untuk mengautentikasi aplikasi atau notebook ke layanan Hugging Face. Anda dapat mengelola token akses Anda di pengaturan Anda.

Token akses memungkinkan aplikasi dan notebook untuk melakukan tindakan tertentu yang ditentukan oleh cakupan peran yang ditunjukkan berikut ini:

• fine-grained: token dengan peran ini dapat digunakan untuk memberikan akses terperinci ke sumber daya tertentu, seperti model tertentu atau model-model dalam organisasi tertentu. Jenis token ini berguna di lingkungan produksi, karena Anda dapat menggunakan token Anda sendiri tanpa membagikan akses ke semua sumber daya Anda.

• read: token dengan peran ini hanya dapat digunakan untuk memberikan akses baca ke repositori yang bisa Anda baca. Ini mencakup repositori publik dan privat yang dimiliki oleh Anda, atau organisasi yang menjadi anggotanya. Gunakan peran ini jika Anda hanya perlu membaca konten dari Hugging Face Hub (misalnya saat mengunduh model privat atau melakukan inferensi).

• write: token dengan peran ini juga memberikan akses tulis ke repositori yang memiliki akses tulis. Gunakan token ini jika Anda perlu membuat atau mendorong konten ke repositori (misalnya, saat melatih model atau mengubah kartu model).

Jika Anda adalah anggota organisasi dengan peran baca/tulis/admin, maka User Access Tokens Anda akan dapat membaca/menulis sumber daya sesuai dengan izin token (baca/tulis) dan keanggotaan organisasi (baca/tulis/admin).

Bagaimana cara mengelola User Access Tokens?

Untuk membuat token akses, buka pengaturan Anda, lalu klik pada tab Access Tokens. Klik tombol New token untuk membuat User Access Token baru.

Pilih peran dan nama untuk token Anda, dan voilà - Anda siap untuk memulai!

Anda dapat menghapus dan memperbarui User Access Tokens dengan mengklik tombol Manage.

Bagaimana cara menggunakan User Access Tokens?

Ada banyak cara untuk menggunakan User Access Token guna mengakses Hugging Face Hub, memberikan Anda fleksibilitas yang dibutuhkan untuk membangun aplikasi hebat di atasnya.

User Access Tokens dapat berupa:

• digunakan sebagai pengganti kata sandi untuk mengakses Hugging Face Hub dengan git atau dengan autentikasi dasar.
• dilewatkan sebagai bearer token saat memanggil Inference Providers.
• digunakan dalam pustaka Python Hugging Face, seperti transformers atau datasets:

from transformers import AutoModel

access_token = "hf_..."

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

Usahakan jangan membocorkan token Anda! Meskipun Anda selalu dapat merotasinya, siapa pun akan dapat membaca atau menulis repositori privat Anda di waktu tersebut, yang merupakan 💩 Lihat Mencabut token yang bocor jika sebuah token telah terekspos.

Praktik terbaik

Kami merekomendasikan Anda membuat satu token akses per aplikasi atau penggunaan. Misalnya, Anda dapat memiliki token terpisah untuk:

• Mesin lokal.
• Notebook Colab.
• Server inferensi kustom yang luar biasa.

Dengan cara ini, Anda dapat membatalkan satu token tanpa memengaruhi penggunaan lainnya.

Kami juga merekomendasikan penggunaan token bergranularitas halus saja untuk penggunaan produksi. Dampaknya, jika bocor, akan berkurang, dan token tersebut dapat dibagikan di antara organisasi Anda tanpa memengaruhi akun Anda.

Sebagai contoh, jika aplikasi produksi Anda memerlukan akses baca ke model yang terkontrol, anggota organisasi Anda dapat meminta akses ke model tersebut dan kemudian membuat token bergranularitas halus dengan akses baca ke model itu. Token ini kemudian dapat digunakan dalam aplikasi produksi Anda tanpa memberikan akses ke semua model privat Anda.

Untuk pipeline CI/CD

Jika Anda hanya memerlukan akses dari alur kerja CI/CD (GitHub Actions, GitLab CI, CircleCI, …), Anda dapat sepenuhnya menghindari penyimpanan token akses sebagai rahasia CI. Lihat Penerbit Terpercaya, yang menukar token identitas OpenID Connect (OIDC) dari penyedia CI Anda dengan token Hub berumur pendek di awal setiap eksekusi — baik yang berlingkup repositori (untuk menerbitkan model, dataset, Spaces, atau kernel, atau untuk menariknya secara read-only) maupun yang berlingkup pengguna (untuk membaca repositori bergerbang yang dapat Anda akses dan mendapatkan batas laju akun Anda).

Untuk organisasi Enterprise

Jika organisasi Anda perlu menerbitkan token secara programatik untuk anggota tanpa mengharuskan setiap pengguna membuat token mereka sendiri, lihat OAuth Token Exchange. Fitur rencana Enterprise ini ideal untuk membangun platform internal, pipeline CI/CD, atau integrasi kustom yang perlu mengakses sumber daya Hugging Face atas nama anggota organisasi.

Mencabut token yang bocor

Jika salah satu token Anda bocor, hapus atau perbarui dari tab Access Tokens di pengaturan Anda.

Jika Anda menemukan token akses Hugging Face milik orang lain, Anda dapat membatalkannya dengan endpoint POST /api/credentials/revoke. Anda tidak memerlukan hak apa pun atas akun atau organisasi yang memiliki token tersebut.

# 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}\"]}"

Anda dapat meneruskan beberapa nilai token dalam array credentials dalam satu panggilan, yang sangat berguna untuk pipeline pemindaian rahasia yang melaporkan temuan dalam batch.

Setiap token yang dikirim dan cocok dengan token yang sudah ada akan dinonaktifkan secara langsung dan berhenti berfungsi di mana pun — berbeda dengan penarikan di tingkat organisasi, yang hanya memutus akses token ke satu organisasi. Pemilik token akan diberi tahu melalui email dan perlu membuat token baru untuk memulihkan akses.

Endpoint selalu merespons dengan 202 Accepted, terlepas dari apakah token yang Anda kirimkan ada atau tidak, sehingga responsnya tidak dapat digunakan untuk memeriksa apakah sebuah token valid. Mengirimkan token yang sama lagi tidak berbahaya: panggilan berulang tidak melakukan apa-apa dan pemilik hanya diberi tahu sekali.

Untuk mencegah kebocoran nilai token dalam riwayat shell atau log, teruskan melalui variabel lingkungan atau file, dan hindari menempelkan token mentah langsung ke baris perintah.

Token dalam organisasi dengan kebijakan manajemen token

Organisasi pada paket Team dan Enterprise dapat menerapkan kebijakan token yang memengaruhi cara token Anda berfungsi saat mengakses sumber daya organisasi tersebut.

Ketika token Anda memerlukan persetujuan (organisasi Team & Enterprise)

Saat Anda membuat token bergranularitas halus yang di-scope ke organisasi yang memerlukan persetujuan administrator, token tersebut secara otomatis masuk ke status Pending. Token tidak dapat mengakses sumber daya organisasi tersebut sampai disetujui oleh administrator. Anda akan menerima notifikasi email ketika token Anda disetujui atau ditolak.

Anda dapat memeriksa status dari halaman daftar token Anda. Token yang masih diproses menampilkan ikon jam pasir berwarna oranye di samping lencana izinnya, sedangkan token yang ditolak atau dicabut menampilkan ikon seru berwarna merah. Banner error berwarna merah juga muncul di halaman edit token jika token Anda ditolak atau dicabut.

Jika Anda adalah administrator organisasi, token bergranularitas halus yang Anda buat dengan cakupan organisasi tersebut disetujui secara otomatis — tidak diperlukan langkah peninjauan.

Ketika token Anda ditolak (organisasi Team & Enterprise)

Jika token Anda ditolak, Anda akan menerima notifikasi email. Token tetap ada di akun Anda dan masih dapat digunakan untuk sumber daya di luar organisasi. Token yang ditolak dapat disetujui kemudian oleh administrator, sehingga akses dipulihkan tanpa Anda perlu membuat token baru.

Saat mencoba menggunakan token yang ditolak terhadap sumber daya organisasi, Anda akan menerima error 403.

Ketika token Anda dicabut (organisasi Enterprise)

Pencabutan bersifat permanen. Berbeda dengan penolakan, token yang dicabut tidak dapat dikembalikan. Jika token Anda telah dicabut, Anda harus menghapusnya dan membuat token baru. Jika organisasi memerlukan persetujuan administrator, token baru akan berstatus tertunda.

Saat mencoba menggunakan token yang telah dicabut terhadap sumber daya organisasi, Anda akan menerima error 403 dengan pesan: “Token Anda telah dicabut oleh administrator organisasi, Anda tidak lagi dapat mengakses sumber daya organisasi. Silakan hubungi mereka untuk informasi lebih lanjut.”

Pencabutan hanya memengaruhi organisasi yang melakukan pencabutan. Token tersebut tetap berfungsi normal untuk semua sumber daya lain yang berada dalam cakupannya.

Ketika organisasi Anda hanya mengizinkan token berbutir halus (organisasi Team & Enterprise)

Jika organisasi Anda telah menetapkan kebijakan yang memerlukan token bergranularitas halus, token baca/tulis akan ditolak dengan error 403 saat digunakan terhadap sumber daya organisasi tersebut.