Autentikasi

Claude API mendukung tiga cara untuk mengautentikasi permintaan:

Kunci API dan Workload Identity Federation memberikan akses yang sama ke endpoint Claude API. Pilih kunci API untuk memulai dengan cepat: kunci pribadi untuk pengembangan Anda sendiri, atau kunci akun layanan untuk apa pun yang dibagikan. Beralih ke Workload Identity Federation ketika beban kerja Anda sudah memiliki identitas yang diterbitkan platform yang dapat Anda federasikan. Gunakan App Attest untuk aplikasi iOS dan macOS yang Anda distribusikan ke pengguna akhir.

Kunci API

Kunci API adalah rahasia statis yang Anda hasilkan di Claude Console dan kirim pada setiap permintaan sebagai bearer token di header Authorization.

Jenis kunci

Saat Anda membuat kunci, Anda memilih jenisnya, yang menentukan apa yang dapat dilakukan kunci, di mana kunci bekerja, dan kapan kunci berhenti bekerja:

Kunci pribadi dan kunci akun layanan didukung identitas: masing-masing milik pengguna atau akun layanan yang sudah dikelola organisasi Anda, dan setiap permintaan bertindak sebagai identitas tersebut. Ketika identitas tersebut dihapus dari organisasi, kunci berhenti bekerja. Ini berarti kunci tidak akan secara tidak sengaja bertahan lebih lama dari orang atau beban kerja yang memilikinya. Utamakan kunci ini daripada kunci workspace untuk integrasi baru.

Gunakan kunci pribadi untuk pengembangan dan skrip Anda sendiri. Kunci pribadi yang dibagikan bertindak sebagai satu orang dan rusak ketika orang tersebut pergi. Untuk beban kerja yang dibagikan atau otomatis (CI, layanan produksi), minta admin organisasi membuat akun layanan sehingga beban kerja memiliki identitasnya sendiri.

Kunci API workspace masih berfungsi tetapi harus dianggap lawas; kunci yang didukung identitas atau Workload Identity Federation lebih diutamakan. Untuk bermigrasi, lihat Mengganti kunci API workspace.

Membuat dan menggunakan kunci

• Membuat kunci: Di Claude Console, buka halaman API keys (platform.claude.com/settings/keys) dan klik Create key. Beri nama kunci dan pilih masa kedaluwarsa. Atur Linked account ke diri Anda sendiri untuk kunci pribadi, atau ke akun layanan untuk kunci yang digunakan bersama oleh beberapa pengguna. Anda juga dapat membatasi cakupan kunci ke workspace tertentu, sehingga Anda tidak perlu mengatur ID workspace secara manual dalam permintaan berikutnya.
• Menggunakan kunci: Kirim sebagai Authorization: Bearer <key> pada permintaan HTTP langsung, atau atur variabel lingkungan ANTHROPIC_API_KEY dan SDK klien akan mengambilnya secara otomatis.

POST /v1/messages
Authorization: Bearer YOUR_API_KEY
anthropic-version: 2023-06-01
content-type: application/json

Header lawas x-api-key: YOUR_API_KEY masih didukung sebagai pengganti Authorization.

Simpan kunci API di secrets manager, rotasi secara berkala, dan nonaktifkan atau hapus kunci apa pun yang Anda curigai telah bocor. Di halaman kunci API di Claude Console, Disable dapat dibatalkan (Admin API melaporkan status kunci sebagai "inactive", dan Re-enable mengembalikannya ke "active"), sedangkan Delete bersifat permanen: kunci diarsipkan dan tetap muncul di List API Keys dengan status: "archived". Kunci yang kedaluwarsa hanya dapat dihapus. Anda juga dapat mengatur masa kedaluwarsa saat membuat kunci untuk membatasi berapa lama kredensial yang bocor tetap dapat digunakan.

client = Anthropic(api_key="my-anthropic-api-key")
# atau, dengan ANTHROPIC_API_KEY yang diatur di environment:
client = Anthropic()

Memilih workspace

Kunci API yang dibuat untuk workspace tertentu hanya berfungsi di workspace tersebut, dan permintaan API yang menggunakan kunci ini dapat menghilangkan ID workspace.

Jika kunci API Anda tidak dibatasi cakupannya ke workspace, Anda harus menentukan ID workspace di header anthropic-workspace-id untuk setiap permintaan. Lihat contoh berikut untuk cara mengatur header ini dalam permintaan atau di SDK.

Admin API menerima kunci pribadi atau kunci akun layanan hanya jika kunci tersebut tidak dibatasi cakupannya ke workspace tertentu.

Anda dapat menemukan ID workspace di kolom ID pada halaman Workspaces (platform.claude.com/settings/workspaces) di Claude Console, atau dengan memanggil endpoint List Workspaces. List Workspaces menyertakan Default Workspace hanya jika Anda meneruskan include_default=true; ID-nya juga ada di header respons anthropic-workspace-id dari setiap permintaan yang berjalan di sana.

client = Anthropic()  # reads ANTHROPIC_API_KEY

# Diperlukan pada setiap permintaan untuk kunci multi-workspace.
# Hilangkan extra_headers untuk kunci single-workspace.
message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    extra_headers={"anthropic-workspace-id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"},
)
print(message.content)

# Atau atur sekali untuk setiap permintaan dari klien ini:
workspace_client = Anthropic(
    default_headers={"anthropic-workspace-id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"},
)

Jika permintaan yang dibuat dengan kunci yang tidak dibatasi cakupannya ke workspace menghilangkan header, API mengembalikan 400 invalid_request_error:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "anthropic-workspace-id is required when authenticating with an identity-linked API key; send the id of the workspace this request acts in."
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

Nilai header yang bukan ID workspace yang valid mengembalikan 400 invalid_request_error dengan pesan anthropic-workspace-id header must be a valid workspace ID. Jika workspace tidak ada, atau pengguna atau akun layanan kunci tidak memiliki akses ke sana, API mengembalikan 404 not_found_error dengan pesan Workspace `<id>` not found., respons yang sama seperti untuk workspace yang tidak dikenal.

Workload Identity Federation memilih workspace saat pertukaran token sebagai gantinya; lihat referensi WIF untuk detailnya.

Kedaluwarsa kunci

Saat Anda membuat kunci API dari halaman kunci API di Claude Console, Anda memilih kedaluwarsa: preset (3 jam, 1 hari, 7 hari, atau 30 hari), durasi kustom, atau Never untuk kunci yang Anda simpan di secrets manager dan rotasi sendiri. Jika organisasi Anda memiliki kebijakan kedaluwarsa maksimum, Console membatasi preset dan durasi kustom ke maksimum kebijakan, dan Never tidak tersedia. Kunci yang ada mempertahankan perilaku saat ini; kedaluwarsa diatur pada waktu pembuatan dan tidak dapat diubah setelahnya. Pilihan kedaluwarsa yang sama berlaku saat Anda membuat kunci Admin API di Claude Console.

Anthropic mengirim email kepada pembuat kunci saat kedaluwarsa mendekat: 7 hari sebelum kedaluwarsa untuk kunci yang dibuat dengan masa pakai minimal 14 hari, dan 1 hari sebelumnya untuk kunci dengan masa pakai minimal 7 hari. Kunci dengan masa pakai lebih pendek kedaluwarsa tanpa email peringatan.

Setelah kunci kedaluwarsa, permintaan yang dibuat dengannya mengembalikan 401 authentication_error. Buat kunci baru untuk memulihkan akses; kunci yang kedaluwarsa tidak dapat diaktifkan kembali.

Tabel kunci API di Console menampilkan masa kedaluwarsa setiap kunci, dan Admin API melaporkan timestamp expires_at setiap kunci pada endpoint List API Keys dan Retrieve API Key, sehingga Anda dapat mengaudit dan merotasi kunci sebelum kedaluwarsa. Field ini bernilai null untuk kunci tanpa masa kedaluwarsa.

Kedaluwarsa membatasi masa pakai kredensial yang bocor, tetapi bukan pengganti kebersihan rahasia. Terlepas dari kedaluwarsa, simpan kunci di secrets manager dan nonaktifkan atau hapus kunci apa pun yang Anda curigai telah bocor.

Mengganti kunci API workspace

Jika Anda memiliki kunci workspace, Anda mungkin ingin menggantinya dengan Workload Identity Federation atau kunci pribadi atau akun layanan. Ini memberikan keamanan dan observabilitas yang lebih baik.

Lihat Workload Identity Federation untuk detail tentang mengonfigurasi Workload Identity Federation, yang lebih diutamakan daripada kunci berumur panjang.

Untuk mengganti kunci workspace dengan kunci pribadi atau akun layanan:

1. Tentukan jenis kunci. Perkakas Anda sendiri harus menggunakan kunci pribadi. Beban kerja yang dibagikan atau tanpa pengawasan harus menggunakan kunci akun layanan.
2. Buat akun layanan jika diperlukan. Anda mungkin perlu meminta admin organisasi untuk membuatnya di halaman Service accounts (platform.claude.com/settings/service-accounts) di Claude Console dan menambahkannya ke workspace yang relevan.
3. Buat kunci baru. Buat secara khusus untuk workspace integrasi kecuali beberapa workspace diperlukan.
4. Terapkan kunci baru. Ganti kunci lama di mana pun integrasi membacanya, biasanya variabel lingkungan ANTHROPIC_API_KEY atau entri secrets manager. Untuk kunci multi-workspace, kirim juga header anthropic-workspace-id seperti yang ditunjukkan di Memilih workspace.
5. Hapus kunci lama. Pastikan permintaan berhasil, lalu hapus kunci workspace di halaman kunci API di Claude Console.

Workload Identity Federation

Workload Identity Federation (WIF) memungkinkan beban kerja mengautentikasi dengan identity token berumur pendek yang diterbitkan oleh penyedia identitas (IdP) yang sudah Anda percayai, seperti AWS IAM, Google Cloud, atau penerbit OIDC yang sesuai standar apa pun (seperti GitHub Actions, akun layanan Kubernetes, SPIFFE, Microsoft Entra ID, atau Okta). Beban kerja menukar JWT yang diterbitkan IdP-nya di POST /v1/oauth/token untuk access token Claude API berumur pendek, dan SDK menyegarkan token tersebut secara otomatis sebelum kedaluwarsa. Tidak ada string sk-ant-api... untuk dibuat, didistribusikan, atau dirotasi.

Federasi menghapus kunci Claude API berumur panjang dari lingkungan Anda, yang mengecilkan radius ledakan kredensial yang bocor dan memungkinkan Anda mengelola akses dengan kontrol IdP yang sama yang sudah Anda gunakan untuk sumber daya cloud. Federasi, dengan sendirinya, tidak menjamin keamanan end-to-end: rantai kepercayaan hanya sekuat konfigurasi penyedia identitas Anda, dan rahasia berumur panjang satu lompatan di hulu (misalnya, kredensial cloud statis yang dapat membuat token IdP) masih dapat melemahkannya. Pasangkan federasi dengan kontrol penyedia Anda, seperti daftar izin IP, MFA, dan logging audit.

Untuk mengonfigurasi federasi, Anda membuat tiga sumber daya di Claude Console (akun layanan, penerbit federasi, dan aturan federasi) lalu mengarahkan SDK Anda ke aturan tersebut. Lihat Workload Identity Federation untuk panduan pengaturan lengkap.

App Attest

App Attest mengautentikasi aplikasi iOS dan macOS yang memanggil Claude API langsung dari perangkat. Setiap instalasi membuktikan bahwa itu adalah build asli dan tidak dimodifikasi dari aplikasi yang Anda daftarkan di Claude Console, menggunakan layanan App Attest Apple. Anthropic kemudian menerbitkan access token berumur pendek untuk perangkat yang menagih penggunaan ke workspace Anda. Token dibatasi cakupannya ke workspace Anda, kedaluwarsa setelah satu jam, dan hanya mengotorisasi panggilan Messages API.

Untuk mendaftarkan aplikasi Anda dan mendapatkan client ID, lihat App Attest untuk aplikasi iOS dan macOS.

Langkah selanjutnya