Profil pengguna untuk atribusi pelanggan akhir

"User profiles" (profil pengguna, atau "profil") memberi tahu Anthropic untuk pelanggan akhir mana setiap permintaan API ditujukan. Dengan begitu, "safety enforcement action" (tindakan penegakan keamanan), seperti penahanan atau pemblokiran, dapat diterapkan pada satu pelanggan akhir alih-alih seluruh organisasi Anda. Ketika hal itu terjadi, lalu lintas Anda yang lain tidak terpengaruh.

Jika Anda mengoperasikan platform atau gateway, atau menjual kembali akses API, permintaan yang Anda kirim untuk pelanggan akhir Anda tiba di bawah organisasi Anda. Anthropic menjalankan "safety classifier" (pengklasifikasi keamanan) otomatis pada lalu lintas API. Tanpa profil pada permintaan, satu pelanggan akhir dapat memicu tindakan penegakan yang berlaku untuk seluruh organisasi Anda.

Anda mendaftarkan setiap pelanggan akhir satu kali dengan POST /v1/user_profiles dan menyimpan ID uprof_ yang dikembalikannya. Kemudian Anda mengirim ID tersebut di header anthropic-user-profile-id pada setiap permintaan yang Anda buat atas nama pelanggan akhir tersebut.

Profil tidak dikenakan biaya dan tidak memengaruhi harga.

Tentukan siapa yang mendapatkan profil

Apa yang diwakili oleh sebuah profil bergantung pada cara Anda menjual Claude: seseorang yang menggunakan produk Anda, atau perusahaan tempat Anda menjual kembali akses API. Kedua kasus ini mencakup sebagian besar platform. Field access_type pada profil menyatakan kasus mana yang berlaku.

Apa isi profil dan bagaimana Anthropic menggunakannya

Profil hanya berisi apa yang Anda kirim tentang pelanggan akhir, ditambah status program apa pun yang ditetapkan Anthropic. Profil tidak berisi konten percakapan. Anthropic menggunakan detail yang Anda kirim untuk mengatribusikan permintaan, memantau penyalahgunaan, menegakkan Kebijakan Penggunaan, serta memungkinkan pengajuan dan akses ke program akses tepercaya. Anthropic tidak memverifikasi detail tersebut.

Anthropic memproses profil sesuai dengan Kebijakan Privasi.

Sebelum Anda memulai

Anda membuat dan mengelola profil di salah satu dari berikut ini:

• Organisasi di Claude API.
• Organisasi di Claude Platform on AWS. Principal yang memanggil memerlukan tindakan IAM profil pengguna.
• Deployment Microsoft Foundry yang di-hosting di Anthropic, bukan yang di-hosting di Azure. Anda tidak memerlukan organisasi di Claude API atau Claude Platform on AWS. Gunakan endpoint Foundry Anda, dengan base URL dan autentikasi yang sama dengan yang Anda gunakan untuk inferensi.

Amazon Bedrock dan Google Cloud tidak memiliki endpoint /v1/user_profiles. Jika inferensi Anda berjalan di sana, buat profil Anda di organisasi di Claude API atau Claude Platform on AWS. Di Amazon Bedrock, profil hanya berfungsi dengan Claude di Amazon Bedrock. Lihat Atribusikan permintaan di Amazon Bedrock dan Google Cloud.

Tempatkan lalu lintas yang Anda kirim untuk pelanggan akhir Anda di satu organisasi dan penggunaan internal Anda sendiri di organisasi lain. Profil dimiliki oleh organisasi, bukan workspace, sehingga workspace terpisah dalam satu organisasi tidak cukup. Hanya organisasi untuk lalu lintas pelanggan akhir yang memerlukan profil pengguna. Untuk membuat organisasi lain di Claude API, lihat bagian "How to create a new organization" dari Creating and managing Workspaces in the Claude Console di Claude Help Center.

Contoh-contoh ini memanggil Claude API dengan kunci API. Anda tidak memerlukan kunci Admin API. Di Claude Platform on AWS, gunakan base URL dan autentikasinya.

Buat profil untuk setiap pelanggan akhir

Buat satu profil untuk setiap pelanggan akhir yang lalu lintasnya Anda kirim ke Claude. Buat sekali saja, dalam alur onboarding pelanggan Anda. POST /v1/user_profiles tidak "idempotent" (idempoten), sehingga setiap panggilan membuat profil baru, bahkan ketika reference_id cocok dengan profil yang sudah ada. Jika Anda sudah memiliki pelanggan akhir tanpa profil, lihat panduan nanti di bagian ini tentang mendaftarkan basis pelanggan yang sudah ada.

Contoh berikut mendaftarkan perusahaan yang membeli akses API melalui gateway, sehingga menetapkan access_type ke passthrough. Untuk profil application, hilangkan access_type, dan deskripsikan satu pengguna akhir di name dan external_user_details alih-alih perusahaan. Tentukan siapa yang mendapatkan profil membandingkan kedua jenis akses tersebut.

client = anthropic.Anthropic()

profile = client.user_profiles.create(
    name="Acme Analytics, Inc.",
    access_type="passthrough",
    external_user_details={"reference_id": "cust-8f2a1c", "country": "US"},
)

print(profile.id)

Responsnya adalah profil baru:

{
  "type": "user_profile",
  "id": "uprof_011CZkZCu8hGbp5mYRQgUmz9",
  "name": "Acme Analytics, Inc.",
  "access_type": "passthrough",
  "external_user_details": {
    "reference_id": "cust-8f2a1c",
    "onboarded_at": null,
    "account_status": null,
    "entity_type": null,
    "country": "US",
    "name_hash": null,
    "email_hash": null
  },
  "metadata": {},
  "programs": {
    "cyber": null,
    "efs": null
  },
  "created_at": "2026-03-15T10:00:00Z",
  "updated_at": "2026-03-15T10:00:00Z"
}

Simpan id pada catatan pelanggan Anda, dan minta instance layanan Anda membacanya dari sana alih-alih membuat profil sendiri. Anda mengambil, memperbarui, dan menghapus profil berdasarkan id tersebut. Field programs bersifat read-only, dan atribusi tidak menggunakannya. Field ini menyimpan status pelanggan akhir di setiap program yang dijalankan Anthropic. Untuk arti nilai-nilainya, lihat program mana yang berlaku untuk profil.

Tidak ada batas jumlah profil dalam sebuah organisasi, tetapi pembuatan profil dikenai "rate limit" (batas laju). Sebelum Anda mendaftarkan basis pelanggan yang sudah ada secara massal, hubungi tim akun Anthropic Anda.

Apa yang perlu diberitahukan kepada Anthropic tentang pelanggan akhir

Setiap field bersifat opsional. Anda dapat mengirim name, metadata, dan field-field berikut di external_user_details: entity_type, country, reference_id, onboarded_at, account_status, name_hash, dan email_hash. Referensi Create a profile menjelaskan setiap field, beserta tipe, format, dan batas panjangnya.

Ikuti aturan berikut saat Anda menetapkan field:

• Nilai yang tidak diketahui: Jika Anda tidak mengetahui suatu nilai, hilangkan alih-alih mengirim placeholder. Anda dapat mengganti nilai di external_user_details nanti, tetapi Anda tidak dapat mengosongkannya.
• Nama perusahaan: Untuk profil passthrough, kirim nama resmi perusahaan di name jika Anda mengetahuinya.
• Negara: Di country, kirim negara pelanggan akhir, bukan negara Anda.
• ID Anda sendiri: Di reference_id, kirim pengidentifikasi stabil Anda sendiri untuk pelanggan akhir. Nilai ini tidak harus unik.
• Nama dan alamat email yang tidak dapat Anda bagikan: Hilangkan name dan kirim external_user_details.name_hash sebagai gantinya. Untuk alamat email, kirim external_user_details.email_hash. Profil tidak memiliki field untuk alamat itu sendiri.
• Hash: Hitung hash sendiri, dengan fungsi yang Anda pilih. Hash menunjukkan kepada Anthropic profil mana milik Anda yang memiliki nama atau alamat email yang sama. Gunakan fungsi yang sama serta normalisasi huruf besar-kecil dan spasi yang sama untuk setiap profil, karena hanya nilai yang dihitung dengan cara yang sama yang akan cocok.

Atribusikan setiap permintaan

Kirim ID profil di header anthropic-user-profile-id pada setiap permintaan yang Anda buat atas nama pelanggan akhir. SDK dan CLI memiliki argumen yang mengirim header tersebut untuk Anda: user_profile_id.

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    user_profile_id="uprof_011CZkZCu8hGbp5mYRQgUmz9",
)

print(message)

Header ini bekerja dengan cara yang sama pada permintaan penghitungan token, Message Batches, dan kompatibilitas OpenAI SDK. Pada batch, header ini berlaku untuk setiap permintaan dalam batch tersebut.

Claude API, Claude Platform on AWS, dan deployment Microsoft Foundry yang di-hosting di Anthropic memeriksa ID pada setiap permintaan. Jika ID tidak valid formatnya atau bukan milik organisasi yang mengirim permintaan, API mengembalikan 400 invalid_request_error. Secara default, platform-platform ini hanya menerima ID profil pada permintaan dari organisasi yang membuat profil tersebut. Ini berarti bahwa jika Anda mengirim lalu lintas di bawah lebih dari satu organisasi, misalnya satu di Claude API dan satu di Claude Platform on AWS, permintaan dari organisasi yang tidak membuat profil tersebut akan mendapatkan 400 yang sama.

Message Batches adalah pengecualian: pembuatan batch hanya memeriksa format ID. Jika ID yang formatnya valid bukan milik organisasi yang mengirim batch, batch tetap dibuat, dan setiap permintaan di dalamnya kemudian gagal dengan hasil errored yang berisi invalid_request_error yang sama.

Atribusikan permintaan di Amazon Bedrock dan Google Cloud

ID profil dari kedua jenis akses juga berfungsi di Claude di Amazon Bedrock dan di Google Cloud. ID ini tidak berfungsi dengan integrasi Amazon Bedrock sebelumnya yang Anda panggil dengan InvokeModel atau Converse. Anda menggunakan kredensial organisasi Anthropic Anda hanya untuk membuat dan mengelola profil. Inferensi tetap menggunakan kredensial AWS atau Google Cloud Anda yang sudah ada.

Di Claude di Amazon Bedrock, letakkan ID di tingkat teratas body permintaan:

{
  "model": "anthropic.claude-opus-5-5",
  "max_tokens": 1024,
  "user_profile_id": "uprof_011CZkZCu8hGbp5mYRQgUmz9",
  "messages": [{ "role": "user", "content": "Hello, Claude" }]
}

Tautkan setiap akun AWS yang mengirim permintaan ke Claude di Amazon Bedrock, dan setiap proyek Google Cloud yang mengirim permintaan di Google Cloud, ke organisasi Anthropic yang membuat profil Anda:

1. Admin atau pemilik organisasi tersebut memulai penautan di Verification Portal di portal.anthropic.com, di bawah Linked accounts.
2. Seseorang yang dapat mengelola IAM di akun AWS atau proyek Google Cloud menjalankan perintah yang disediakan portal.
3. Admin atau pemilik menyelesaikan verifikasi di portal.

Program yang berlaku untuk profil hanya berlaku untuk permintaan suatu akun setelah akun tersebut ditautkan dan portal menampilkannya sebagai Linked. Program-program tersebut mencakup program yang disetujui untuk organisasi pelanggan akhir setelah pelanggan akhir menautkan profil ke organisasi tersebut.

Claude di Amazon Bedrock dan Google Cloud memeriksa format ID tetapi tidak mencari profilnya. Keduanya menolak ID yang formatnya tidak valid dengan 400. Keduanya menerima ID apa pun yang formatnya valid, sehingga respons yang berhasil tidak mengonfirmasi bahwa ID tersebut cocok dengan sebuah profil. Permintaan tanpa ID diproses tanpa atribusi, dan jika memicu tindakan penegakan, tindakan tersebut berlaku untuk seluruh organisasi Anda.

Identifikasi pengguna individual dalam sebuah perusahaan

Profil passthrough mengidentifikasi perusahaan, bukan orang yang membuat permintaan. Jika permintaan berasal dari satu orang yang dapat diidentifikasi, kirim juga pengidentifikasi untuk orang tersebut di field metadata.user_id pada permintaan Messages. Ini adalah objek metadata milik permintaan itu sendiri, bukan field metadata milik profil. Pengidentifikasi ini opsional, dan membantu Anthropic mendeteksi penyalahgunaan oleh satu orang.

Jaga profil tetap terkini

Perbarui profil ketika detail atau status akun pelanggan akhir berubah, dan hapus profil ketika mereka menutup akun atau meminta Anda menghapus data mereka.

Perbarui profil

POST /v1/user_profiles/{id} hanya mengubah field yang Anda kirim. Misalnya, gunakan ini ketika perusahaan melakukan rebranding atau Anda menangguhkan akun.

• name dan access_type menggantikan nilai yang tersimpan.
• Setiap field yang Anda kirim di external_user_details menggantikan nilai yang tersimpan. Anda tidak dapat mengosongkan nilai. API menolak null dengan 400.
• metadata digabungkan per kunci. Kunci yang Anda kirim menimpa nilai yang tersimpan, string kosong menghapus kunci tersebut, dan kunci yang tidak Anda kirim tetap seperti semula.

Contoh berikut menandai akun sebagai ditangguhkan dan menghapus kunci metadata trial_cohort.

client = anthropic.Anthropic()

profile = client.user_profiles.update(
    "uprof_011CZkZCu8hGbp5mYRQgUmz9",
    external_user_details={"account_status": "suspended"},
    metadata={"trial_cohort": ""},
)

print(profile)

Hapus profil

DELETE /v1/user_profiles/{id} menghapus profil secara permanen beserta semua yang Anda berikan untuknya, termasuk name, external_user_details, dan metadata. Ini tidak menghapus catatan trust and safety yang disimpan Anthropic tentang ID profil tersebut.

Hapus profil ketika pelanggan akhir menutup akunnya atau meminta Anda menghapus datanya. Sebelum Anda menghapus profil, berhentilah mengirim ID-nya pada permintaan pelanggan akhir tersebut. Jika pelanggan akhir tetap bersama Anda setelah permintaan penghapusan data, buat profil baru dan beralihlah ke ID-nya. Kemudian hapus profil yang lama.

client = anthropic.Anthropic()

deleted = client.user_profiles.delete("uprof_011CZkZCu8hGbp5mYRQgUmz9")

print(deleted.id)

Respons mengulang ID dengan "type": "user_profile_deleted". Jika penghapusan mengembalikan error server, coba lagi. 404 pada percobaan ulang berarti penghapusan pertama telah berhasil.

Setelah penghapusan, endpoint profil mengembalikan 404 untuk ID tersebut. Hingga sekitar 10 menit, permintaan inferensi yang membawa ID yang telah dihapus masih dapat berhasil. Setelah itu, platform yang memeriksa ID pada setiap permintaan menolak permintaan tersebut dengan 400. Claude di Amazon Bedrock dan Google Cloud tidak mencari profil, sehingga keduanya tetap menerimanya.

Langkah selanjutnya

Referensi API berisi field, tipe, dan batas setiap endpoint: Create a profile, Retrieve a profile, Update a profile, dan List profiles.

Jika persetujuan program pelanggan akhir harus berlaku ketika mereka menggunakan Claude melalui platform Anda, lihat Kirim tautan ke Verification Portal kepada pelanggan akhir.