用於終端客戶歸屬的使用者設定檔

「User profiles」（使用者設定檔，以下簡稱「設定檔」）會告訴 Anthropic 每個 API 請求是為您的哪一位終端客戶發出的。如此一來，「safety enforcement action」（安全強制措施），例如暫停（hold）或封鎖（block），就可以只套用於單一終端客戶，而非您的整個組織。在這種情況下，您的其餘流量不會受到影響。

如果您經營平台或閘道，或轉售 API 存取權，您為終端客戶發送的請求都會以您的組織名義送達。Anthropic 會對 API 流量執行自動化的「safety classifiers」（安全分類器）。如果請求上沒有設定檔，單一終端客戶就可能觸發套用於您整個組織的強制措施。

您只需使用 POST /v1/user_profiles 為每位終端客戶註冊一次，並儲存其傳回的 uprof_ ID。之後，在您代表該終端客戶發出的每個請求中，都在 anthropic-user-profile-id 標頭中傳送該 ID。

設定檔不會計費，也不會影響定價。

決定誰需要設定檔

設定檔代表的對象取決於您銷售 Claude 的方式：使用您產品的個人，或是您轉售 API 存取權的公司。這兩種情況涵蓋了大多數平台。設定檔的 access_type 欄位會說明適用哪一種情況。

設定檔包含的內容以及 Anthropic 如何使用它

設定檔只包含您傳送的終端客戶相關資訊，以及 Anthropic 設定的任何計畫狀態。它不包含對話內容。Anthropic 會使用您傳送的詳細資訊來歸屬請求、監控濫用行為、執行使用政策，以及啟用受信任存取計畫的申請與存取。Anthropic 不會驗證這些詳細資訊。

Anthropic 會依照隱私權政策處理設定檔。

開始之前

您可以在下列其中一處建立和管理設定檔：

• Claude API 上的組織。
• Claude Platform on AWS 上的組織。呼叫的主體需要具備使用者設定檔 IAM 動作。
• 託管於 Anthropic 的 Microsoft Foundry 部署，而非託管於 Azure 的部署。您不需要 Claude API 或 Claude Platform on AWS 上的組織。請使用您的 Foundry 端點，並使用與推論相同的基礎 URL 和驗證方式。

Amazon Bedrock 和 Google Cloud 沒有 /v1/user_profiles 端點。如果您的推論在這些平台上執行，請在 Claude API 或 Claude Platform on AWS 上的組織中建立設定檔。在 Amazon Bedrock 上，設定檔僅適用於 Claude in Amazon Bedrock。請參閱在 Amazon Bedrock 和 Google Cloud 上歸屬請求。

請將您為終端客戶發送的流量保留在一個組織中，並將您自己的內部用量保留在另一個組織中。設定檔屬於組織而非工作區，因此在同一組織中使用不同的工作區是不夠的。只有用於終端客戶流量的組織需要使用者設定檔。若要在 Claude API 上建立另一個組織，請參閱 Claude 說明中心內在 Claude Console 中建立和管理工作區的「How to create a new organization」章節。

範例使用 API 金鑰呼叫 Claude API。您不需要 Admin API 金鑰。在 Claude Platform on AWS 上，請使用其基礎 URL 和驗證方式。

為每位終端客戶建立設定檔

為每位您將其流量傳送至 Claude 的終端客戶建立一個設定檔。請在您的客戶導入流程中建立一次即可。POST /v1/user_profiles 並非「idempotent」（冪等）操作，因此每次呼叫都會建立新的設定檔，即使 reference_id 與現有設定檔相符也是如此。如果您已有尚未建立設定檔的終端客戶，請參閱本節稍後關於註冊現有客戶群的指引。

以下範例註冊一家透過閘道購買 API 存取權的公司，因此將 access_type 設為 passthrough。若是 application 設定檔，請省略 access_type，並在 name 和 external_user_details 中描述單一終端使用者，而非公司。決定誰需要設定檔比較了這兩種存取類型。

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)

回應即為新的設定檔：

{
  "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"
}

請將 id 儲存在您的客戶記錄中，並讓您的服務執行個體從該處讀取，而不是各自建立設定檔。您可以透過該 id 擷取、更新和刪除設定檔。programs 欄位為唯讀，歸屬不會使用它。它記錄終端客戶在 Anthropic 執行的每個計畫中的狀態。關於其值的意義，請參閱哪些計畫適用於設定檔。

組織中的設定檔數量沒有上限，但設定檔的建立受到速率限制。在大量註冊現有客戶群之前，請聯絡您的 Anthropic 客戶團隊。

要告訴 Anthropic 哪些終端客戶資訊

每個欄位都是選填的。您可以傳送 name、metadata，以及 external_user_details 中的這些欄位：entity_type、country、reference_id、onboarded_at、account_status、name_hash 和 email_hash。建立設定檔參考文件說明了每個欄位的類型、格式和長度限制。

設定欄位時請遵循以下規則：

• 未知的值： 如果您不知道某個值，請省略它，而不是傳送預留位置值。您之後可以取代 external_user_details 中的值，但無法清除它。
• 公司名稱： 對於 passthrough 設定檔，如果您知道公司的法定名稱，請在 name 中傳送。
• 國家： 在 country 中，請傳送終端客戶的國家，而非您的國家。
• 您自己的 ID： 在 reference_id 中，請傳送您為該終端客戶使用的穩定識別碼。它不必是唯一的。
• 您無法分享的姓名和電子郵件地址： 請省略 name，改為傳送 external_user_details.name_hash。對於電子郵件地址，請傳送 external_user_details.email_hash。設定檔沒有用於存放地址本身的欄位。
• 雜湊值： 請自行計算雜湊值，並使用您選擇的函式。這些雜湊值可讓 Anthropic 知道您的哪些設定檔共用相同的姓名或電子郵件地址。請對每個設定檔使用相同的函式以及相同的大小寫和空白正規化方式，因為只有以相同方式計算的值才會相符。

歸屬每個請求

在您代表終端客戶發出的每個請求中，都在 anthropic-user-profile-id 標頭中傳送設定檔 ID。SDK 和 CLI 提供一個會為您傳送該標頭的引數：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)

此標頭在 token 計數、Message Batches 和 OpenAI SDK 相容性請求上的運作方式相同。在批次上，它會套用於批次中的每個請求。

Claude API、Claude Platform on AWS 以及託管於 Anthropic 的 Microsoft Foundry 部署會在每個請求上檢查 ID。如果 ID 格式錯誤或不屬於發送請求的組織，API 會傳回 400 invalid_request_error。根據預設，這些平台只接受來自建立該設定檔之組織的請求所帶的設定檔 ID。這表示如果您以多個組織的名義發送流量，例如一個在 Claude API 上、一個在 Claude Platform on AWS 上，那麼來自未建立該設定檔之組織的請求也會收到相同的 400。

Message Batches 是例外：建立批次時只會檢查 ID 的格式。如果格式正確的 ID 不屬於發送批次的組織，批次仍會被建立，但其中的每個請求隨後都會失敗，並產生包含相同 invalid_request_error 的 errored 結果。

在 Amazon Bedrock 和 Google Cloud 上歸屬請求

任一存取類型的設定檔 ID 也適用於 Claude in Amazon Bedrock 和 Google Cloud。它不適用於您透過 InvokeModel 或 Converse 呼叫的早期 Amazon Bedrock 整合。您只會使用 Anthropic 組織的憑證來建立和管理設定檔。推論仍使用您現有的 AWS 或 Google Cloud 憑證。

在 Claude in Amazon Bedrock 上，請將 ID 放在請求主體的最上層：

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

請將每個向 Claude in Amazon Bedrock 發送請求的 AWS 帳戶，以及每個在 Google Cloud 上發送請求的 Google Cloud 專案，連結到建立您設定檔的 Anthropic 組織：

1. 該組織的管理員或擁有者在 portal.anthropic.com 的 Verification Portal 中，於 Linked accounts 下開始連結。
2. 能夠管理該 AWS 帳戶或 Google Cloud 專案中 IAM 的人員執行入口網站提供的命令。
3. 管理員或擁有者在入口網站中完成驗證。

適用於設定檔的計畫，只有在帳戶完成連結且入口網站顯示其為 Linked 之後，才會套用於該帳戶的請求。這些計畫包括終端客戶將設定檔連結到其組織後，該終端客戶的組織所獲核准的計畫。

Claude in Amazon Bedrock 和 Google Cloud 會檢查 ID 的格式，但不會查詢設定檔。它們會以 400 拒絕格式錯誤的 ID。它們接受任何格式正確的 ID，因此成功的回應並不代表該 ID 與某個設定檔相符。沒有 ID 的請求會在未歸屬的情況下通過，如果它觸發強制措施，該措施會套用於您的整個組織。

識別公司內的個別使用者

passthrough 設定檔識別的是公司，而非發出請求的個人。如果請求來自一位可識別的個人，請同時在 Messages 請求的 metadata.user_id 欄位中傳送該人員的識別碼。這是請求本身的 metadata 物件，而非設定檔的 metadata 欄位。此識別碼為選填，有助於 Anthropic 偵測個人的濫用行為。

保持設定檔為最新狀態

當終端客戶的詳細資訊或帳戶狀態變更時，請更新設定檔；當他們關閉帳戶或要求您清除其資料時，請刪除設定檔。

更新設定檔

POST /v1/user_profiles/{id} 只會變更您傳送的欄位。例如，當公司更改品牌或您停用某個帳戶時，請使用它。

• name 和 access_type 會取代已儲存的值。
• 您在 external_user_details 中傳送的每個欄位都會取代已儲存的值。您無法清除值。API 會以 400 拒絕 null。
• metadata 會逐鍵合併。您傳送的鍵會覆寫已儲存的值，空字串會刪除該鍵，而您省略的鍵則維持不變。

以下範例將帳戶標記為已停用，並移除 trial_cohort 中繼資料鍵。

client = anthropic.Anthropic()

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

print(profile)

刪除設定檔

DELETE /v1/user_profiles/{id} 會永久刪除設定檔以及您為其提供的所有內容，包括 name、external_user_details 和 metadata。它不會移除 Anthropic 針對該設定檔 ID 保留的信任與安全記錄。

當終端客戶關閉帳戶或要求您清除其資料時，請刪除設定檔。在刪除設定檔之前，請停止在該終端客戶的請求中傳送其 ID。如果終端客戶在提出清除請求後仍繼續使用您的服務，請建立新的設定檔並改用其 ID。然後再刪除舊的設定檔。

client = anthropic.Anthropic()

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

print(deleted.id)

回應會重複該 ID，並附上 "type": "user_profile_deleted"。如果刪除傳回伺服器錯誤，請重試。重試時收到 404 表示第一次刪除已成功。

刪除後，設定檔端點會針對該 ID 傳回 404。在最多約 10 分鐘內，帶有已刪除 ID 的推論請求仍可能成功。之後，會在每個請求上檢查 ID 的平台將以 400 拒絕該請求。Claude in Amazon Bedrock 和 Google Cloud 不會查詢設定檔，因此仍會接受該請求。

後續步驟

API 參考文件列出了每個端點的欄位、類型和限制：建立設定檔、擷取設定檔、更新設定檔和列出設定檔。

如果終端客戶透過您的平台使用 Claude 時應套用其計畫核准，請參閱傳送 Verification Portal 連結給終端客戶。