Security
Autentikasi Claude Code: Semua Metode Login Dijelaskan
Agustus 202612 menit baca
Ia mengikuti urutan presedensi tetap: kredensial penyedia cloud lebih dulu, lalu bearer auth token, lalu API key, lalu skrip apiKeyHelper, lalu token OAuth berumur panjang, lalu kredensial profil Anthropic dan federasi, dan terakhir login langganan. Sesi gateway yang sudah masuk duduk di luar daftar itu dan mengungguli semuanya.
Jalankan perintah setup-token, yang membuka alur otorisasi browser yang sama dengan sign-in lalu mencetak token OAuth berumur satu tahun. Setel ia sebagai environment variable token OAuth di pipeline Anda. Ia berautentikasi dengan langganan Anda, hanya bisa membuat permintaan model, dan tidak dibaca di bare mode.
Di macOS di Keychain sistem yang terenkripsi. Di Linux di sebuah file kredensial di bawah direktori Claude Anda dengan mode 0600. Di Windows di file yang sama di bawah direktori profil pengguna Anda, mewarisi kendali aksesnya. Menyetel direktori konfigurasi kustom memindahkan file-nya di Linux dan Windows.
Setel kunci metode login dan UUID organisasi di managed settings. Catat celahnya: pencetakan token dan jalur aplikasi GitHub hanya menegakkan kunci metodenya, login Console hanya dipilih-dahulukan ketimbang diverifikasi, dan sign-in gateway dipilih oleh kunci metodenya ketimbang dibatasi olehnya.
Anda mendapat peringatan saat startup tiga hari sebelumnya, yang tak pernah memblokir permintaan. Begitu login-nya benar-benar kedaluwarsa, tiap permintaan gagal sampai Anda masuk lagi. Ini paling penting untuk pekerjaan yang tak ditunggui: sesi latar atau Remote Control yang hidup lebih lama dari login-nya berhenti maju dan tak bisa pulih sendiri.
Ringkasan Utama
Claude Code bisa berautentikasi dengan langganan claude.ai, API key Console, bearer token, skrip apiKeyHelper, token OAuth berumur panjang, profil Anthropic, atau penyedia cloud — dan ketika beberapa hadir sekaligus, ia memilih satu lewat urutan presedensi tetap. Mengetahui urutan itulah yang mengubah sebagian besar kebingungan autentikasi jadi perbaikan satu baris.
Seorang rekan pernah menghabiskan dua hari dengan keyakinan langganan Max-nya berhenti bekerja. Permintaannya ditagihkan ke organisasi Console yang sudah dinonaktifkan berbulan-bulan sebelumnya, karena sebuah API key masih ter-export di shell profile dari proyek yang sudah ia selesaikan. Claude Code berperilaku persis seperti yang didokumentasikan. Dokumentasi perilaku itu satu tabel, dan kami berdua belum membacanya.
Jadi inilah tabel itu dan semua di sekitarnya: urutan presedensinya, tempat kredensial disimpan di tiap sistem operasi, cara mengautentikasi pipeline CI tanpa browser, menjalankan skrip untuk kredensial yang berotasi, membatasi login ke organisasi Anda berikut jalur tempat pembatasan itu lebih lemah dari kelihatannya, dan apa yang terjadi ketika sebuah login kedaluwarsa di bawah sesi yang tak ditunggui.
Ketika lebih dari satu kredensial hadir, Claude Code memilih dalam urutan tetap, dan yang di puncak daftar mengalahkan semua di bawahnya. Sesi gateway yang sudah masuk duduk sepenuhnya di luar daftar itu: ia pemilihan penyedia dan ia mengungguli semuanya, jadi ketika ia ada, tak satu pun sumber kredensial di bawahnya dipakai.
Urutan presedensinya, tertinggi lebih dulu:
| Kredensial | Untuk apa ia |
|---|---|
| Kredensial penyedia cloud | Dipilih lewat environment variable penyedia untuk Bedrock, Google Cloud, atau Foundry. Tak ada di bawahnya yang dikonsultasikan |
| Bearer auth token | Dikirim sebagai header Authorization. Untuk perutean lewat gateway atau proxy yang berautentikasi dengan bearer token ketimbang API key |
| Sebuah API key | Dikirim sebagai header API key. Di mode interaktif Anda menyetujuinya sekali dan pilihannya diingat; di mode non-interaktif ia selalu dipakai kalau ada |
| Skrip apiKeyHelper | Untuk kredensial dinamis atau berotasi, seperti token berumur pendek dari sebuah vault |
| Token OAuth berumur panjang | Dibuat untuk CI dan skrip. Dibaca lagi di setiap sesi baru sampai Anda membuangnya dari shell profile atau settings |
| Profil, lalu login langganan | Kredensial profil Anthropic dan federasi berada di atas sebuah login di kebanyakan konfigurasi. Login langganan dari alur sign-in adalah bawaannya dan jalan terakhirnya |
Konsekuensi yang layak diresapi: API key di lingkungan Anda mengalahkan langganan Anda begitu disetujui. Kalau ia milik organisasi yang dinonaktifkan atau kedaluwarsa, permintaan Anda gagal dengan cara yang tampak seperti akun Anda rusak. Membuang variabelnya lalu memeriksa kredensial mana yang aktif makan sepuluh detik dan merupakan langkah pertama yang benar setiap kali.
Penyimpanannya berbeda per platform, dan ketiganya dikelola lewat perintah sign-in dan sign-out ketimbang dengan menyunting file. Kalau Anda mencoba mengarahkan permintaan ke endpoint lain, environment variable base URL adalah mekanismenya — menyunting file kredensialnya bukan.
# Where the credential actually lives
macOS the encrypted system Keychain
Linux ~/.claude/.credentials.json mode 0600
Windows %USERPROFILE%\.claude\.credentials.json
(inherits your profile directory's access controls)
# CLAUDE_CONFIG_DIR moves the file on Linux and Windows.
# Claude Code manages it through /login and /logout — to send
# requests somewhere else, set ANTHROPIC_BASE_URL instead of
# editing this file.
/status # which credential is active, and for which org
/login # sign in, or renew a login about to expire
/logout # sign out; also resets first-launch setup stateCI tidak punya browser, jadi ada dua rute yang didukung dan keduanya cocok untuk situasi berbeda. Token berumur panjang adalah yang sederhana: ia berautentikasi dengan langganan Anda, bertahan setahun, dan dihasilkan oleh perintah yang membuka alur browser yang sama dengan yang Anda pakai secara interaktif. Credential helper adalah jawaban yang tepat ketika token-nya berotasi.
# For CI, a browser login is not available. Mint a token:
claude setup-token
export CLAUDE_CODE_OAUTH_TOKEN=your-token
# - one year, tied to a Pro, Max, Team or Enterprise plan
# - the command does NOT save it anywhere; copy it yourself
# - MODEL REQUESTS ONLY: it cannot establish Remote Control
# sessions or fetch claude.ai connectors. Locally configured
# MCP servers still work
# - bare mode does NOT read it — use an API key or a helper
# For rotating credentials from a vault, run a script instead:
{ "apiKeyHelper": "/usr/local/bin/fetch-claude-key.sh" }
CLAUDE_CODE_API_KEY_HELPER_TTL_MS=… # default: 5 min, or on 401
# Over 10 seconds to return and you get a warning in the prompt
# bar. Three failed attempts and requests fail outright.Token berumur panjang punya batasan sengaja yang layak diantisipasi. Ia hanya bisa membuat permintaan model, jadi ia tidak bisa membangun sesi Remote Control atau mengambil connector claude.ai — MCP server yang dikonfigurasi lokal tetap bekerja. Dan bare mode sama sekali tidak membacanya, jadi skrip yang memberi flag itu butuh API key atau helper. Kedua batasan itu bukan bug; keduanya mengagetkan orang sekali.
Dua kunci managed settings mengarahkan metode login mana yang dipakai developer dan mensyaratkan login claude.ai milik organisasi tertentu. Keduanya alat yang tepat, dan punya celah yang layak diketahui sebelum Anda mengandalkannya sebagai kendali:
Setelan yang sama juga menentukan apakah sesi yang tidak memakai kredensial login boleh mulai sama sekali. API key di lingkungan, bearer token, atau credential helper diblokir saat startup, karena keanggotaan organisasi tidak bisa diverifikasi untuk kredensial dari lingkungan. Itu sifat yang sungguh berguna: ia mencegah developer melewati pembatasan organisasi Anda dengan meng-export key pribadi.
Dua hal tidak diblokir. Sesi penyedia cloud mulai normal, karena ia berautentikasi terhadap cloud Anda ketimbang terhadap Anthropic — batasi itu lewat kebijakan identitas dan akses cloud Anda. Dan kredensial profil Anthropic serta federasi juga tidak diblokir, dan kunci-kunci itu tidak memeriksa organisasi mana yang memiliki profilnya.
Login yang tinggal tiga hari lagi kedaluwarsa menghasilkan peringatan saat startup yang menyuruh Anda memperbaruinya. Peringatan itu tak pernah memblokir permintaan — autentikasinya tetap bekerja sampai login-nya benar-benar kedaluwarsa, setelah itu tiap permintaan gagal sampai Anda masuk lagi. Anda bisa melihat keadaannya sebelum itu terjadi: perintah status menunjukkan baris login-kedaluwarsa berikut organisasi dan email yang tersimpan untuknya.
Memperbarui lebih awal paling penting untuk apa pun yang tak ditunggui. Sesi latar atau sesi Remote Control yang hidup lebih lama dari login-nya berhenti maju begitu kredensialnya kedaluwarsa dan tak bisa pulih sampai seorang manusia masuk. Kalau Anda menjalankan pekerjaan otonom panjang, perlakukan peringatan tiga hari itu sebagai tugas, bukan pemberitahuan.
Kalau organisasi Anda memakai Workload Identity Federation atau CLI Anthropic, sebuah profil bernama atau sepasang variabel federasi bisa menyediakan kredensialnya, dan keduanya berada di atas login Anda. Satu aturan layak diketahui: profil aktif yang ditulis oleh login interaktif CLI Anthropic berada di bawah kredensial sign-in yang berfungsi, justru supaya profil sisa tidak diam-diam memindahkan permintaan Anda dari akun yang Anda masuki. Selagi salah satu dari ini terpilih, fitur yang butuh login claude.ai Anda tidak tersedia.
Pelajari urutan presedensinya dan periksa kredensial mana yang aktif sebelum mengubah apa pun — kedua kebiasaan itu bersama-sama menyelesaikan sebagian besar masalah autentikasi dalam waktu kurang dari semenit. Untuk CI, cetak sebuah token ketimbang mengirimkan API key, dan ketahui dua batasannya. Dan kalau Anda administrator, baca apa yang sebenarnya ditegakkan kunci pembatasan organisasinya di tiap jalur login, karena celahnya spesifik dan bukan jalur yang akan Anda tebak.
Sumber & bacaan lanjutan