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. Beralihlah 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

"API key" (kunci API) adalah rahasia statis yang Anda buat di Claude Console dan kirimkan pada setiap permintaan di header x-api-key.

Jenis kunci

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

Kunci pribadi dan kunci akun layanan didukung oleh 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 berfungsi. Ini berarti kunci tidak akan secara tidak sengaja bertahan lebih lama daripada 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 bersama atau otomatis (CI, layanan produksi), mintalah admin organisasi membuat akun layanan agar beban kerja memiliki identitasnya sendiri.

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

Membuat dan menggunakan kunci

• Buat kunci: Buka Settings → API keys di Claude Console dan klik Create key. Beri nama kunci dan pilih kedaluwarsa. Atur Linked account ke diri Anda sendiri untuk kunci pribadi, atau ke akun layanan untuk kunci yang dibagikan ke beberapa pengguna. Anda juga dapat membatasi cakupan kunci ke workspace tertentu, yang memungkinkan Anda melewati pengaturan ID workspace secara manual pada permintaan berikutnya.
• Gunakan kunci: Atur header x-api-key pada permintaan HTTP langsung, atau atur variabel lingkungan ANTHROPIC_API_KEY dan SDK klien akan mengambilnya secara otomatis.

POST /v1/messages
x-api-key: YOUR_API_KEY
anthropic-version: 2023-06-01
content-type: application/json

Simpan kunci API di pengelola rahasia, rotasi secara berkala, dan nonaktifkan atau hapus kunci apa pun yang Anda curigai telah bocor. Di halaman API keys, Disable dapat dibatalkan (Admin API melaporkan status kunci sebagai "inactive", dan Re-enable mengembalikannya ke "active"), sedangkan Delete bersifat permanen: kunci diarsipkan dan masih muncul di List API Keys dengan status: "archived". Kunci yang kedaluwarsa hanya dapat dihapus. Anda juga dapat mengatur 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 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 suatu 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 Settings → Workspaces di Claude Console, atau dengan memanggil endpoint List Workspaces. Keduanya tidak mencantumkan ID Default Workspace: baca ID tersebut dari header respons anthropic-workspace-id dari permintaan apa pun yang berjalan di sana (misalnya, permintaan yang dibuat dengan kunci workspace dari Default Workspace), atau dari scope.workspace_id pada kunci semacam itu di List API Keys.

client = Anthropic()  # reads ANTHROPIC_API_KEY

# Wajib pada setiap permintaan untuk kunci multi-workspace.
# Hilangkan extra_headers untuk kunci single-workspace.
message = client.messages.create(
    model="claude-opus-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 suatu workspace menghilangkan header tersebut, 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 pemilik kunci tidak memiliki akses ke workspace tersebut, 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 pada saat pertukaran token; lihat referensi WIF untuk detailnya.

Kedaluwarsa kunci

Saat Anda membuat kunci API dari halaman API keys 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 pengelola rahasia dan rotasi sendiri. Jika organisasi Anda memiliki kebijakan kedaluwarsa maksimum, Console membatasi preset dan durasi kustom hingga maksimum kebijakan, dan Never tidak tersedia. Kunci yang sudah ada mempertahankan perilakunya saat ini; kedaluwarsa diatur pada saat 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 berlaku setidaknya 14 hari, dan 1 hari sebelumnya untuk kunci dengan masa berlaku setidaknya 7 hari. Kunci dengan masa berlaku 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 API keys di Console menampilkan 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 kedaluwarsa.

Kedaluwarsa membatasi masa berlaku kredensial yang bocor, tetapi bukan pengganti kebersihan rahasia. Terlepas dari kedaluwarsa, simpan kunci di pengelola rahasia 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 kunci 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 kunci akun layanan:

1. Tentukan jenis kunci. Tooling Anda sendiri sebaiknya menggunakan kunci pribadi. Beban kerja bersama atau tanpa pengawasan sebaiknya menggunakan kunci akun layanan.
2. Buat akun layanan jika diperlukan. Anda mungkin harus meminta admin organisasi untuk membuatnya di Settings → Service accounts dan menambahkannya ke workspace yang relevan.
3. Buat kunci baru. Buat kunci tersebut khusus untuk workspace integrasi kecuali jika diperlukan beberapa workspace.
4. Deploy kunci baru. Ganti kunci lama di mana pun integrasi membacanya, biasanya variabel lingkungan ANTHROPIC_API_KEY atau entri pengelola rahasia. 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 API keys.

Workload Identity Federation

"Workload Identity Federation" (federasi identitas beban kerja), atau WIF, memungkinkan beban kerja melakukan autentikasi dengan token identitas berumur pendek yang diterbitkan oleh "identity provider" (penyedia identitas), atau IdP, yang sudah Anda percayai, seperti AWS IAM, Google Cloud, atau penerbit OIDC apa pun yang sesuai standar (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 dengan token akses Claude API berumur pendek, dan SDK memperbarui token tersebut secara otomatis sebelum kedaluwarsa. Tidak ada string sk-ant-api... yang perlu dibuat, didistribusikan, atau dirotasi.

Federasi menghilangkan kunci Claude API berumur panjang dari lingkungan Anda, yang memperkecil radius dampak kredensial yang bocor dan memungkinkan Anda mengelola akses dengan kontrol IdP yang sama yang sudah Anda gunakan untuk sumber daya cloud. Federasi tidak, dengan sendirinya, menjamin keamanan end-to-end: rantai kepercayaan hanya sekuat konfigurasi penyedia identitas Anda, dan rahasia berumur panjang satu langkah di hulu (misalnya, kredensial cloud statis yang dapat membuat token IdP) masih dapat melemahkannya. Padukan federasi dengan kontrol penyedia Anda, seperti allowlist IP, MFA, dan pencatatan 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 penyiapan lengkap.

App Attest

App Attest mengautentikasi aplikasi iOS dan macOS yang memanggil Claude API langsung dari perangkat. Setiap instalasi membuktikan bahwa dirinya adalah build asli dan tidak dimodifikasi dari aplikasi yang Anda daftarkan di Claude Console, menggunakan layanan App Attest dari Apple. Anthropic kemudian menerbitkan token akses berumur pendek untuk perangkat tersebut yang menagihkan 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