Linked billing
讓您的客戶透過 OAuth 將其 Claude Platform 組織連結到您的應用程式,並將 Claude 用量計費至客戶的組織。
Linked billing 讓您的客戶能透過他們自己的 Claude 組織,支付您應用程式中的 Claude 用量。客戶只需將其 Claude 組織連結到您的應用程式一次。API 將此連結稱為「connection」(連線)。客戶連結之後,您可以在每個 Claude API 請求上選擇由客戶或由您付費。客戶可以隨時取消連結您的應用程式。如果您標記為由客戶付費的請求無法向客戶計費,Claude API 會拒絕該請求,而不是向您計費。
本指南適用於其應用程式使用者主要為 Claude Platform 客戶的開發人員。您會在應用程式中新增一個「Link your Claude organization」按鈕。您的使用者點擊該按鈕、登入 Claude,並核准您的應用程式針對客戶指示您發出的 Claude API 請求向其 Claude 組織計費。接著,您的應用程式會在由客戶付費的請求中新增 billing_policy 欄位。
符合資格的客戶與端點
符合資格的客戶: 只有當客戶的 Claude Platform 組織直接向 Anthropic 支付其 API 用量時,才能以此方式向其計費。預付額度與發票計費皆符合資格。透過雲端市集(AWS、Google Cloud 或 Azure)計費的組織無法透過此整合計費。僅有 Claude 訂閱方案的組織也是如此。針對這些組織的請求會以 403 user_profile_not_billable 遭到拒絕。
請求會在您的組織中執行,因此適用的是您的速率限制、模型存取權、服務層級、資料保留和加密金鑰。您客戶自己的資料安排不適用於這些請求,包括「zero data retention」(零資料保留),即 ZDR、「business associate agreement」(業務夥伴協議),即 BAA,以及「customer-managed encryption keys」(客戶管理的加密金鑰),即 CMEK。對於此用量需要 HIPAA、FERPA 或 CMEK 保障的客戶,請勿進行連結。
支援的端點:billing_policy 支援於:
/v1/messages- 已知限制:向您的客戶計費(
bill_to: "user_profile")的請求無法使用需計費的程式碼執行功能(API 會回傳 400),因此請以bill_to: "self"或不帶billing_policy的方式傳送這些請求。
- 已知限制:向您的客戶計費(
/v1/chat/completions/v1/messages/count_tokens接受billing_policy欄位但會忽略它,因此您可以針對即將傳送的完全相同主體計算 token 數。
Message Batches(/v1/messages/batches)目前尚不支援向您的客戶計費。請以 bill_to: "self" 或不帶 billing_policy 的方式傳送批次中的請求,這些請求將照常向您計費。批次中設定了 bill_to: "user_profile" 的請求會被拒絕:其結果為 errored 並附帶 invalid_request_error,您和您的客戶都不會因此被計費,而該批次中的其他請求則會照常執行。
如需請求其他端點的支援,請聯絡您的 Anthropic 客戶團隊。
哪些額度可以付款
並非所有額度都能支付平台向客戶計費的請求。可以支付的項目取決於被計費的組織:如果您向客戶計費,則為該客戶;如果平台向您計費,則為您的組織。
在 Claude Console 中為該組織購買的額度,可以支付這些請求。如果該組織採用發票計費,則會就這些請求收到發票。
Anthropic 提供的部分促銷額度無法支付這些請求,其中包括 Claude Max、Ultra 和 Team 方案隨附的每月 API 額度。來自 Anthropic 合作夥伴、創投及新創計畫的額度,不符合支付這些請求的資格。
當該組織帳戶上沒有任何項目可以支付某個請求時,Claude API 可能會以 402 拒絕該請求。回應中不會說明拒絕的原因是額度不足還是支出限制。請參閱預期的錯誤。
設定流程
以下三個步驟只需執行一次。它們會向 Anthropic 註冊您的應用程式。完成之後,要連結哪個使用者設定檔說明了您在建立使用者設定檔之前需要了解的一項規則。
步驟 1:建立應用程式
在 Claude Console 中建立「OAuth app」(OAuth 應用程式)。這是向 Anthropic 識別您產品的註冊:它將您的「redirect URI」(重新導向 URI)與一個用戶端 ID 綁定,而其名稱就是您的使用者在核准頁面上看到的名稱。
您組織中具有管理員角色的成員在 Console 中開啟 OAuth 應用程式頁面,然後點擊建立。輸入您應用程式的名稱和重新導向 URI(核准後瀏覽器返回的您應用程式中的位址)。在 What the app can do 下,選擇 Bill and link to organizations。
新應用程式的頁面隨即開啟。複製 Console 為該應用程式顯示的用戶端 ID。您的應用程式會在步驟 5 請求核准頁面時、步驟 6 重新導向瀏覽器時,以及步驟 8 交換代碼時傳送此 ID,讓 Anthropic 知道是哪個應用程式發出請求。用戶端 ID 是公開的。在外觀分頁上,設定您應用程式的名稱、首頁和標誌 URL。
在設定分頁上,新應用程式一開始處於測試階段,其 Who can link 會顯示 Test users only。在您發布應用程式且應用程式上線之後,此設定會顯示 Any Claude user。
步驟 2:設定用戶端驗證
設定您的後端如何向 auth.claude.com 證明其請求來自您的應用程式。這取代了用戶端密鑰:Anthropic 不會為 OAuth 應用程式核發用戶端密鑰。
在應用程式的 Client authentication 分頁上,選擇您的身分識別提供者(為您後端的 token 簽署的簽發者)。若要新增一個,請點擊 Register a new issuer。接著設定這些 token 必須符合的主旨模式,或在進階比對選項下設定宣告條件。儲存後,該分頁會顯示預期的 audience。您的用戶端斷言的 aud 宣告必須完全等於該值。
步驟 3:設定您後端的身分
您的後端需要擁有自己的身分才能呼叫 Claude API。請建立兩項內容:
- 「Service account」(服務帳戶)。 這是您 Claude 組織中的非人類帳戶。您的後端在呼叫 Claude API 時會以此帳戶的身分進行驗證。
- 第二條聯合規則。 與步驟 2 中應用程式用戶端驗證的規則類似,它讓您的後端能使用您自己身分提供者的 token 進行驗證。
若要在 Claude Console 中設定這些項目,請依照工作負載身分聯合指南操作。
接著,在應用程式的 Client authentication 分頁上,選擇該服務帳戶作為應用程式的操作員服務帳戶。只有該服務帳戶獲授權傳送推論請求,並將計費歸屬至已連結的使用者設定檔。一個服務帳戶只能作為一個 OAuth 應用程式的操作員。
根據預設,任何以該服務帳戶身分驗證的請求,都可以透過在 Messages API 中設定使用者設定檔標頭和 bill_to,向每位已連結的客戶計費。若要取得僅限於特定連線的驗證 token,請參閱每個連線的 OAuth token。在連結客戶之前,請為您的應用程式設定工作區。步驟 8 會為每位客戶回傳這樣的 token,並要求應用程式在您的組織中指定一個供推論執行的預設工作區。如果您需要每個連線的「refresh token」(重新整理 token),也請為您的應用程式開啟 Offline access。接著,在連結客戶之前,於步驟 5 的授權流程中請求 offline_access。
要連結哪個使用者設定檔
「User profile」(使用者設定檔)是您自己 Claude 組織中代表您其中一位客戶的記錄。每個向客戶計費的請求都會包含該設定檔的 ID,讓 Anthropic 知道要向哪位客戶計費。關於設定檔的其他用途,請參閱用於終端客戶歸屬的使用者設定檔。
在連結您的第一位客戶之前,請先確定每位客戶由哪個使用者設定檔代表。在同一個應用程式中,連線是一對一的:
- 客戶的 Claude 組織只能連結到您的一個使用者設定檔。
- 一個使用者設定檔只能連結到一個 Claude 組織。
客戶的 Claude 組織是您的使用者在核准您的應用程式時所選擇的組織。若要了解客戶的各個團隊如何使用 Claude 組織,請詢問客戶。若要將一對一規則套用到您的客戶記錄:
- 同一位客戶的多個團隊共用一個 Claude 組織: 為所有團隊使用同一個使用者設定檔。
- 每個團隊都有自己的 Claude 組織: 為每個組織建立一個使用者設定檔。
只要符合一對一規則,您組織中任何有效的使用者設定檔都可以進行連結。連結不會變更該設定檔、其 ID 或其用量歷程記錄。如果您將第二個使用者設定檔連結到已經連結的 Claude 組織,核准會遭到拒絕:請參閱 user_profile_already_linked。
每位人員各有一個使用者設定檔
您可能已經為每位使用您產品的人員建立了使用者設定檔。其中可能有多位人員為同一位客戶工作。在這種情況下,Anthropic 建議您為客戶的 Claude 組織再建立一個使用者設定檔,並連結該設定檔。
要傳送的設定檔 ID 取決於由誰為請求付費:
- 您向客戶計費的請求: 傳送客戶設定檔的 ID。若也要在
/v1/messages請求中識別該人員,請將metadata.user_id可檢視預覽,內含 API 參考文件連結——按 Tab 鍵直到焦點進入卡片,按 Escape 鍵返回。 設為該人員的識別碼。此識別碼為選用,它有助於 Anthropic 偵測個別人員的濫用行為。請使用不透明的值,而非姓名、電子郵件地址或電話號碼。 - 由您付費的請求: 您可以繼續傳送該人員自己的設定檔 ID。
連結每位客戶
對於每位連結其組織的客戶,您都需要執行步驟 4 至 8。以下 Python 程式碼片段需要 Anthropic SDK 和一些標準匯入;請參閱程式碼片段初始化。其他語言和 CLI 的範例會從環境中取得憑證。請確保未設定 ANTHROPIC_API_KEY,因為您的應用程式需要透過工作負載身分聯合進行驗證。
在您產品中客戶管理計費或整合的位置加入一個「Link your Claude organization」按鈕(關於按鈕的 HTML、顏色和標誌,請參閱品牌範例)。告知客戶,若要連結,他們必須在其 Claude 組織中具有管理員或帳單角色。
若要先自行走過這些步驟,請參閱以客戶身分進行測試。
步驟 4:為客戶建立使用者設定檔
為每位客戶的 Claude 組織建立一個使用者設定檔,並將該設定檔的 ID 儲存在您產品中該客戶的記錄上。
如果您已經為此客戶的 Claude 組織建立了使用者設定檔,請略過此步驟,並使用該設定檔的 ID。若要判斷是哪一個設定檔,請參閱要連結哪個使用者設定檔。
def create_user_profile(name: str, customer_id: str) -> str:
profile = client.user_profiles.create(
name=name,
external_user_details={"reference_id": customer_id},
)
return profile.id # "uprof_..."
user_profile_id = create_user_profile("Example Customer Inc.", "your-customer-id-123")如果您的組織轉售 API 存取權,請在建立此設定檔時一併傳送 "access_type": "passthrough"。這些範例省略了 access_type,因此會建立 application 設定檔。關於這兩種類型,請參閱決定誰需要設定檔。
回應包含設定檔的 id,例如 uprof_01HV9Z。
步驟 5:建立推送授權請求 URL
建立一個「pushed authorization request」(推送授權請求),其中參照步驟 4 中該客戶的使用者設定檔。回應會提供一個 request_uri。在下一個步驟中,您會使用它將您的使用者重新導向至核准頁面。
在傳送請求之前,您的後端會建立兩個隨機值,並將其儲存在瀏覽器工作階段和客戶記錄上。步驟 8 會再次使用這兩個值:
- 一個
state值,讓您可以檢查返回您應用程式的瀏覽器就是發起此請求的瀏覽器。 - 一個 PKCE 程式碼驗證器,這是只有您的後端知道的密鑰。請求會攜帶其雜湊值(code challenge),而步驟 8 會傳送驗證器本身,因此只有您的後端能使用返回的代碼。
def push_authorization_request(user_profile_id: str) -> dict:
state = secrets.token_urlsafe(32)
code_verifier = secrets.token_urlsafe(64)
code_challenge = create_s256_code_challenge(code_verifier)
response = httpx.post(
f"{AUTH}/v1/oauth/par",
json={
"response_type": "code",
"client_id": CLIENT_ID,
"redirect_uri": REDIRECT_URI,
"scope": "billing:attribution",
"connection_type": "organization_shared",
"connection_auth_target": "platform",
"user_profile_id": user_profile_id,
"state": state,
"code_challenge": code_challenge,
"code_challenge_method": "S256",
"client_assertion_type": JWT_BEARER,
"client_assertion": client_assertion(),
},
)
response.raise_for_status() # on an error, do not redirect the browser
return {
"state": state,
"code_verifier": code_verifier,
"request_uri": response.json()["request_uri"], # valid for 600 seconds
"user_profile_id": user_profile_id,
}
par = push_authorization_request(user_profile_id)auth.claude.com 會回應 HTTP 201、一個 request_uri,以及 600 秒的 expires_in。request_uri 識別此請求的核准頁面。scope 必須完全是 billing:attribution 或 billing:attribution offline_access。詳細資訊請參閱計費連線的範圍。範例傳送的是 billing:attribution。如果您的應用程式沒有此範圍,請在應用程式權限分頁的計費下新增。
connection_auth_target 必須是 platform:推論請求會在您自己的組織中執行,以操作員服務帳戶身分進行驗證,但可以向客戶計費。
user_profile_id 必須是您組織中有效使用者設定檔的 ID。如果推送授權請求失敗,auth.claude.com 會向您的後端回傳 OAuth 錯誤回應。在這種情況下,請勿重新導向瀏覽器。
步驟 6:將使用者導向 Claude 核准頁面
首先,向您的使用者顯示他們正在連結的是您產品中的哪個帳戶,並告知他們檢查核准頁面所顯示的 Claude 帳戶。該頁面會顯示目前登入的是哪個 Claude 帳戶,並讓使用者切換至其他帳戶。核准頁面只會提供瀏覽器中目前登入之 Claude 帳戶的組織,因此錯誤的帳戶可能會連結錯誤的組織。由使用者所連結的組織付費。
接著,將使用者重新導向至授權端點,該端點會顯示核准頁面。僅包含您的 client_id 和步驟 5 取得的 request_uri。
def authorize_url(par: dict) -> str:
query = urlencode({"client_id": CLIENT_ID, "request_uri": par["request_uri"]})
return f"{AUTH}/oauth/authorize?{query}"
redirect_to = authorize_url(par) # answer the click with a 302 to this URL步驟 7:使用者核准
在此步驟中,您的應用程式不需執行任何動作。使用者會在 auth.claude.com 上完成以下步驟:
- 使用者登入 Claude,除非瀏覽器已經登入。
- 核准頁面會顯示以下畫面,每個畫面都會顯示您應用程式的名稱。關於使用者在每個畫面上的操作,請參閱連結。
- Select an organization,僅在使用者有多個組織可選擇時顯示。
- How billing works。
- Set a monthly spend limit。
- 最後一個含有 Link and authorize 按鈕的畫面。
- 當使用者點擊 Link and authorize 時,
auth.claude.com會將瀏覽器送回您的應用程式。核准頁面不會顯示確認畫面。
如果使用者取消或無法核准,則不會建立任何連線:請參閱如果連結未完成。
步驟 8:處理回呼並儲存連線
核准後,auth.claude.com 會帶著一次性代碼和您的 state 值將瀏覽器送回您的重新導向 URI。這個發送至您重新導向 URI 的請求稱為「callback」(回呼)。您的後端會將代碼交換為連線 ID,並將其儲存在客戶的記錄上。這樣就完成了連線。回呼可能帶有 error 參數而沒有代碼。此時並未建立任何連線:請參閱如果連結未完成。
檢查 state 是否與您在步驟 5 儲存的值相符,然後立即從您的後端連同 PKCE 程式碼驗證器一起交換代碼。該代碼僅能使用一次,並會在 5 分鐘後過期。
def handle_callback(par: dict, params: dict) -> str:
if not secrets.compare_digest(
params.get("state", "").encode(), par["state"].encode()
):
raise ValueError("state does not match")
if "error" in params: # for example access_denied
raise PermissionError(params["error"])
code = params["code"] # single-use, expires after 5 minutes
response = httpx.post(
f"{AUTH}/v1/oauth/token",
json={
"grant_type": "authorization_code",
"code": code,
"code_verifier": par["code_verifier"],
"redirect_uri": REDIRECT_URI,
"client_id": CLIENT_ID,
"client_assertion_type": JWT_BEARER,
"client_assertion": client_assertion(),
},
timeout=10, # a response that times out loses the tokens in it
)
response.raise_for_status()
tokens = response.json()
# 若要使用該連線的權杖,請儲存 tokens["access_token"]、其到期
# 時間(取自 tokens["expires_in"]),以及搭配 offline_access 時的
# tokens["refresh_token"],作為機密存放於此:該授權碼無法再次交換。
# "ocon_...";請將其儲存於客戶紀錄中
return tokens["connection_id"]回應包含連線 ID 和該連線的存取 token,該 token 可以進行驗證並向進行核准的客戶計費。如果客戶核准了 offline_access,回應也會包含重新整理 token。請立即儲存 connection_id 和這些 token:交換只會回傳這些 token 一次。儲存 token 說明了該回應。
本頁中呼叫 Claude API 的範例會以步驟 3 的服務帳戶身分進行驗證,而不是使用此回應中的 token。使用連線的存取 token 呼叫 Claude 說明如何改用該 token。
回應不會識別使用者連結的是哪個 Claude 組織。
完成的連線並不保證 Anthropic 能向客戶計費。例如,客戶的組織可能不屬於符合資格的客戶。關於 Claude API 如何檢查這一點,請參閱更新對 Claude 的呼叫和預期的錯誤。由於有此檢查,請將您的成功訊息措辭為「已連結」,而非「計費已啟用」。
如果交換以 unauthorized_client 遭拒,請參閱代碼交換回傳 unauthorized_client。
以客戶身分進行測試
若要確認連結是否正常運作,請連結您自己的一個組織。您需要先準備以下項目:
- 您自己的第二個 Claude 組織,用來扮演客戶。您無法將應用程式連結到擁有它的組織。核准頁面不會提供該組織。第二個組織必須屬於符合資格的客戶。
- 該組織中一位具有管理員或帳單角色的人員,負責核准連結。
- 在您的應用程式上線之前,該人員必須在您應用程式的 Test users 清單中。此清單位於應用程式設定分頁的 Who can link 下。以該人員 Claude 帳戶的電子郵件地址新增他們,並點擊 Save changes。當您的應用程式處於測試階段時說明了所適用的支出上限。將某人從清單中移除,會終止其所核准的連結。
接著,執行步驟 4 至 8,並讓該人員在步驟 7 中核准。連結建立後,該使用者設定檔會在 Console 中您的 User profiles 頁面上顯示為 Linked。
如果連結未完成
當使用者未完成核准,或 auth.claude.com 拒絕核准時,不會建立任何連線。以下項目涵蓋 Linked billing 特有的結果。關於所有其他錯誤,請參閱 OAuth 參考中的錯誤。
您的重新導向 URI 收到 error=access_denied
該請求也會帶有您的 state 值。在下列情況中,您的重新導向 URI 會收到此錯誤:
- 使用者在任何核准畫面上點擊 Cancel。
- 核准頁面沒有可提供給使用者的組織,而使用者點擊了返回您應用程式的按鈕。例如:
- 使用者在任何 Claude Platform 組織中都不具有管理員或帳單角色。
- 使用者唯一的組織就是擁有您應用程式的組織。請參閱以客戶身分進行測試。
- 使用者設定檔已連結到另一個 Claude 組織,而使用者在該組織中不具有管理員或帳單角色。
- 在您的應用程式上線之前,使用者不在其 Test users 清單中。
在此清單的每種情況中,error_description 都會顯示 the user declined the request,因此您無法藉此區分這些情況。
還有一個原因出在您應用程式的設定中。如果您的應用程式已上線,且 Who can link 顯示僅限您的組織,則您組織以外的任何人都無法連結該應用程式。請選擇 Any Claude user 並點擊 Save changes。
告知使用者連結未完成,且不要假設他們拒絕了。請他們檢查登入時所使用的 Claude 帳戶,以及他們在欲連結之組織中的角色。使用者取消或返回之後,request_uri 便無法再次使用,因此若要讓使用者再試一次,請從步驟 5 重新開始。
您的應用程式收到 user_profile_already_linked
客戶的 Claude 組織已經透過您的另一個使用者設定檔連結到您的應用程式。auth.claude.com 會要求使用者與您聯絡。如果使用者返回您的應用程式,您的重新導向 URI 會收到 error=user_profile_already_linked 和您的 state 值。當您在步驟 8 中交換代碼時,token 端點也可能回傳此錯誤。例如,當該組織在此期間透過另一個使用者設定檔完成連結時,就會發生這種情況。
Anthropic 不會告知您客戶連結的是哪個 Claude 組織,因此您無法事先得知這一點。步驟 5 中的推送授權請求會成功,而 auth.claude.com 只有在使用者核准時才會拒絕該連線。
此錯誤不會指出持有該連線的使用者設定檔。最有可能的持有者是此客戶的另一個已連結設定檔。Anthropic 不會顯示設定檔連結到哪個組織,因此請在採取行動之前先與客戶確認。如果該設定檔持有該連線,請執行以下其中一項:
- 在您向此客戶計費的請求中,傳送該使用者設定檔的 ID。
- 依照取消連結客戶所述終止該連線,然後使用遭拒的使用者設定檔再次執行步驟 5 至 8。
如果此客戶的設定檔都沒有連結,使用者可能選擇了屬於您另一位客戶的組織。請從步驟 5 重新開始,並讓使用者檢查他們所選擇的組織。
您的重新導向 URI 沒有收到任何內容
您的應用程式無法偵測以下兩種情況:
- 使用者關閉了核准頁面。
request_uri已過期或已被使用過。此時核准頁面會顯示錯誤,且不會將瀏覽器送回您的應用程式。
如果使用者在沒有回呼的情況下返回您的產品,請從步驟 5 重新開始。未使用的 request_uri 會在您建立後 10 分鐘過期。
代碼交換回傳 unauthorized_client
您的應用程式尚未針對此請求完成設定。若為工作區問題,error_description 會指出原因。若缺少操作員服務帳戶,它只會顯示 the client is not registered for this grant。拒絕不會用掉代碼,因此在代碼到期之前,您可以再次交換相同的代碼。首先,請在 Claude Console 中檢查以下項目:
| 檢查項目 | 位置 | 修正方式 |
|---|---|---|
| 應用程式具有操作員服務帳戶 | 應用程式 Client authentication 分頁上的 Operator service account | 選擇一個並點擊 Save。步驟 3 說明了如何設定。 |
| 應用程式的工作區存在且未封存 | 設定您的應用程式 | 選擇一個工作區。在應用程式沒有工作區期間,交換同樣會以 unauthorized_client 遭拒。 |
已儲存的服務帳戶可能需要一兩分鐘才會傳達至 auth.claude.com,因此如果交換再次遭拒,請等待這麼久後重試。如果屆時代碼已過期,請讓使用者再次核准(步驟 5 至 8)。關於 error_description 針對連線 token 所指出的原因,請參閱儲存 token 和重新整理 token。
在任何其他情況下,請聯絡您的 Anthropic 客戶團隊。如果 Console 顯示該服務帳戶已不存在,也請這麼做。
發布您的應用程式
在您的應用程式上線之前,只有其 Test users 清單上的人員可以連結它,因此您的客戶無法連結。若要發布應用程式,請在 Claude Console 中應用程式的頁面上點擊 Publish app。隨即會開啟一個對話方塊。
- 如果您的組織採用發票計費,在您於該對話方塊中確認後,應用程式即會上線。
- 否則,您需要先在該對話方塊中證明您控制應用程式的網域,接著 Anthropic 會審查該應用程式。
網域證明: 網域是指您應用程式首頁的網域。每個重新導向 URI 都必須位於該網域或其子網域上,但位於 localhost、127.0.0.1 或 [::1] 上的 URI 除外。證明方式是一筆 DNS TXT 記錄。DNS 變更最多可能需要 48 小時,因此請在您需要客戶連結之前就開始進行。如果您的組織已經證明過涵蓋該首頁及這些重新導向 URI 的網域,對話方塊會略過此證明。已證明的網域涵蓋其子網域。
您會在對話方塊的最後一個步驟中確認。如果該步驟顯示接受 Linked Billing Terms 的核取方塊,請勾選它。接著,在對話方塊中點擊 Publish app。
審查: 審查期間,Console 中應用程式的狀態會顯示 In review。Anthropic 核准後,應用程式即會上線。如果 Anthropic 未核准,狀態會顯示 Not approved,且您無法自行再次發布該應用程式。若要詢問此決定,請聯絡支援團隊。
除非您的組織採用發票計費,否則變更已上線應用程式的名稱、標誌、首頁或重新導向 URI,都會讓應用程式重新進入審查。已連結的客戶會保持連結,並保留他們已儲存的上限。在 Anthropic 核准變更之前,只有 Test users 清單上的人員可以連結該應用程式。
更新對 Claude 的呼叫
針對已連結的客戶,在每次呼叫 /v1/messages 和 /v1/chat/completions 時傳送 anthropic-user-profile-id 標頭。在您向客戶計費的請求中,該標頭的值是持有該客戶連線之使用者設定檔的 ID。設定 billing_policy 的呼叫也必須傳送 user-profiles-billing-2026-10-01 beta 標頭。
已連結客戶的每個請求都會計費給客戶或您,而您可以在每個請求上選擇由誰付費。以下範例展示這兩種情況。
每個連線的 OAuth token 說明了另一種驗證客戶請求的方式:只能向該客戶計費的存取 token。在 /v1/messages 和 /v1/chat/completions 上,使用此類 token 的請求無法向您計費。即使未附上 billing_policy 或 anthropic-user-profile-id 標頭(在它們為選用的情況下),該請求仍會計費給該客戶:請參閱使用連線的存取 token 呼叫 Claude 中的附註。如果該請求指定其他使用者設定檔或設定 bill_to: "self",就會遭到拒絕。切勿將此類 token 用於由您付費的請求。
由您的客戶付費
在請求主體中加入帶有 bill_to: "user_profile" 的 billing_policy,並傳送計費 beta 標頭和設定檔 ID 標頭。
僅在客戶指示您發出的請求上設定 bill_to: "user_profile":也就是客戶及其使用者在您的產品中所產生的 Claude 用量。請勿將您自己的用量向客戶計費,例如測試、評估或為其他客戶進行的工作。Claude API 無法替您檢查這一點,因此這是您的責任。
def message_billed_to_user(user_profile_id: str, prompt: str) -> BetaMessage:
return client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": prompt}],
betas=[BILLING_BETA],
extra_headers={"anthropic-user-profile-id": user_profile_id},
extra_body={
"billing_policy": {"type": "billing_policy", "bill_to": "user_profile"}
},
)如果請求遭到拒絕,請參閱預期的錯誤。
由您付費
若要由您自己付費,可以完全省略 billing_policy(在此情況下,計費 beta 標頭為選用):
def message_billed_to_you(user_profile_id: str, prompt: str) -> Message:
return client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": prompt}],
user_profile_id=user_profile_id,
)或使用 bill_to: "self":
def message_billed_to_self(user_profile_id: str, prompt: str) -> BetaMessage:
return client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": prompt}],
betas=[BILLING_BETA],
extra_headers={"anthropic-user-profile-id": user_profile_id},
extra_body={"billing_policy": {"type": "billing_policy", "bill_to": "self"}},
)每個連線的 OAuth token
您的後端會以您應用程式的操作員服務帳戶身分呼叫 Claude API(步驟 3)。根據預設,任何以該服務帳戶身分驗證的請求,都可以透過傳遞使用者設定檔 ID 標頭並在 Messages API 請求中包含 bill_to,向每位已連結的客戶計費。此預設行為稱為「operator-only tokenless authentication」(僅限操作員的無 token 驗證)。
為了因應您產品的單一租用戶部署或由客戶控管的沙箱環境,您可以取得綁定連線的 OAuth 存取 token 和重新整理 token,而不使用僅限操作員的無 token 驗證。
對於每個連線,步驟 8 中的代碼交換都會回傳該連線專屬的存取 token。該 token 會以您的操作員服務帳戶身分進行驗證,但只能向該連線的客戶計費。它會在 1 小時內過期。
若要個別驗證每個連線:
- 使用離線存取。 為您的應用程式開啟 Offline access,並在步驟 5 中請求
offline_access。如此一來,每個連線也會取得一個重新整理 token,您的後端會用它來請求新的存取 token。若沒有它,客戶必須再次核准才能給您新的存取 token:請以相同的scope再次執行步驟 5 至 8。 - 設定預設工作區。 在您的組織中選擇一個工作區,讓使用這些 token 的請求在其中執行。
- 選擇性地關閉僅限操作員的無 token 驗證。 根據預設,即使客戶的存取 token 已過期,您仍可以操作員服務帳戶身分(透過傳遞使用者設定檔標頭和
bill_to)向已連結的客戶計費。在您關閉僅限操作員的驗證之後,每個向客戶計費的請求都必須使用該客戶的存取 token 進行驗證。 - 使用
billing:attribution。 只有此範圍會為連線提供專屬的 token。您仍可以操作員服務帳戶身分向已連結的客戶計費,如同已淘汰的org:billing_attribution。請參閱計費連線的範圍。
設定您的應用程式
使用連線存取 token 的請求會在您組織的一個工作區中執行。每個應用程式都需要一個工作區,即使您不使用這些 token 也是如此:當您的應用程式沒有工作區時,步驟 8 中的代碼交換會以 unauthorized_client 遭到拒絕。
您組織中具有管理員角色的成員在 Console 中開啟應用程式的 Client authentication 分頁。在操作員服務帳戶下方,找到 Default workspace for platform auth mode OAuth tokens(應用程式的 connection_token_workspace_id 設定)並點擊 Choose workspace。選擇操作員服務帳戶(步驟 3)所屬的工作區。該工作區不得處於已封存狀態。
若要取得重新整理 token,請在應用程式的權限分頁上開啟 Offline access。對應用程式範圍的變更需要幾分鐘才會傳達至 auth.claude.com。
計費連線的範圍
在步驟 5 中,將 scope 傳送為 billing:attribution。若也要取得重新整理 token,請傳送 billing:attribution offline_access。
若要變更已連結客戶的範圍,例如新增 offline_access,請使用客戶現有的使用者設定檔和新的 scope 再次執行步驟 5 至 8。您不需要先取消連結。代碼交換會回傳新的 connection_id,而新的連線會取代先前的連線。請參閱步驟 8 中的附註。
一個應用程式可以同時擁有 billing:attribution 和已淘汰的 org:billing_attribution。您可以在應用程式 Permissions 分頁的 Billing 下新增 billing:attribution。如果您在該處移除 org:billing_attribution,就無法再次新增它。客戶以 org:billing_attribution 核准的連線,會持續透過您的操作員服務帳戶計費,直到連線終止或您關閉僅限操作員的驗證為止。
儲存 token
代碼交換只會回傳 token 一次,因此請在步驟 8 中儲存它們。回應包含 access_token、expires_in(最多 1 小時,以秒為單位)和 connection_id。如果客戶核准了 offline_access,回應也會包含 refresh_token 和 refresh_token_expires_in。重新整理 token 最多持續 1 年,且重新整理不會延長此期限。期限過後,請再次連結客戶。
將 token 及其到期時間儲存在只有負責重新整理的服務才能讀取的密鑰儲存區中。
如果交換以 unauthorized_client 遭拒,error_description 會說明原因,例如工作區遺失或已封存。代碼並未被用掉:請修正原因,並在代碼到期前再次傳送相同的代碼。
使用連線的存取 token 呼叫 Claude
將連線的存取 token 作為 bearer token 傳送於 Authorization 標頭中,以取代您操作員服務帳戶自己的憑證。請勿傳送 x-api-key 標頭。在 Anthropic SDK 中,將 token 傳遞為 auth_token,或設定 ANTHROPIC_AUTH_TOKEN 環境變數。
在 /v1/messages 和 /v1/chat/completions 上,請求會計費給該連線的客戶。anthropic-user-profile-id 標頭和 billing_policy 為選用。只有搭配 billing_policy 時才需要計費 beta 標頭。
在這兩個端點上,您無法使用此 token 為請求付費。僅在這兩個端點、/v1/messages/count_tokens 以及 Models 端點上使用該 token。所有其他請求,以及所有由您付費的請求,都請從您自己的後端以操作員服務帳戶身分傳送。這包括使用需計費的程式碼執行功能的請求,這類請求無法向客戶計費。
Claude API 會拒絕以下請求:
400 invalid_request_error,不含錯誤代碼:請求指定了其他使用者設定檔,或設定了bill_to: "self"。403 permission_error,不含錯誤代碼:請求傳送至 Message Batches 端點。401 authentication_error:token 已過期、已被重新整理取代,或其連線已終止。連線終止後,回應也可能是403 user_profile_not_billable。
重新整理 token
若要更新連線的存取 token,請將其重新整理 token 傳送至 token 端點 https://auth.claude.com/v1/oauth/token,並附上您應用程式的用戶端驗證。請勿傳送 scope 參數。
connection_locks: defaultdict[str, threading.Lock] = defaultdict(threading.Lock)
def error_body(response: httpx.Response) -> dict:
try:
body = response.json()
except ValueError:
return {}
return body if isinstance(body, dict) else {}
def is_lost(response: httpx.Response) -> bool:
"""True for a 5xx response that can follow a refresh that took effect."""
if response.status_code < 500:
return False
# Claude API 格式且帶有 retry-after 標頭的 503 是一種拒絕,
# 不會用掉重新整理權杖。其他所有 5xx 回應皆視為遺失。
paused = (
response.status_code == 503
and error_body(response).get("type") == "error"
and "retry-after" in response.headers
)
return not paused
def hold_error(connection_id: str, reason: str) -> RefreshOnHold:
return RefreshOnHold(
f"Connection {connection_id} is on hold. {reason} Don't send its refresh token"
' again: that can end the connection. See "Link a customer again" in the'
" Linked billing guide."
)
def refresh_connection(connection_id: str, *, force: bool = False) -> tuple[str, int]:
"""Refreshes the connection if its access token is close to its expiry.
Returns the current access token and its expiry time in Unix seconds. Call
this from your schedule, and pass force=True to refresh a token that isn't
close to its expiry. Raises RefreshOnHold when the refresh token can't be sent
again, now and on every later call, and httpx.HTTPStatusError for a refusal
that keeps the refresh token. After RefreshOnHold for a lost refresh, pause
your schedule. Resume with one connection, and resume the others only after
that refresh succeeds or gets a 4xx.
"""
# 此鎖僅在單一程序內有效。若服務有多個副本,請使用
# 所有副本共用的鎖。
with connection_locks[connection_id]:
tokens = load_tokens(connection_id)
if tokens.on_hold:
raise hold_error(
connection_id, "An earlier refresh might have used its refresh token."
)
if not force and tokens.expires_at - time.time() > REFRESH_MARGIN_SECONDS:
return tokens.access_token, tokens.expires_at # not close to expiry
request = {
"grant_type": "refresh_token",
"refresh_token": tokens.refresh_token,
"client_id": CLIENT_ID,
"client_assertion_type": JWT_BEARER,
"client_assertion": client_assertion(),
}
url = f"{AUTH}/v1/oauth/token"
# 在重新整理權杖離開此程序前,先將連線設為暫停。
# 若程序在新權杖儲存前停止,暫停狀態會保留。
save_tokens(connection_id, replace(tokens, on_hold=True))
issued_at = int(time.time())
started = time.monotonic()
# httpx 本身不會重試。請勿加入重試:延遲的重試會終止
# 連線。
try:
response = httpx.post(url, json=request, timeout=REQUEST_TIMEOUT)
lost = is_lost(response)
except (httpx.ConnectError, httpx.ConnectTimeout):
# 未建立任何連線,因此重新整理權杖從未離開此程序。
save_tokens(connection_id, tokens)
raise
except httpx.TransportError:
lost = True
if lost:
# 第一個請求可能已用掉重新整理權杖。第二個請求
# 僅在上述時限內才安全,因此請立即送出一次,否則
# 就不要送出。
if time.monotonic() - started > SECOND_REQUEST_DEADLINE_SECONDS:
raise hold_error(connection_id, "A refresh got no usable answer.")
try:
response = httpx.post(url, json=request, timeout=REQUEST_TIMEOUT)
except httpx.TransportError:
raise hold_error(
connection_id, "Two refreshes got no answer."
) from None
if response.status_code != 200:
# 收到新權杖以外的任何回應後,您無法判斷
# 第一個請求是否已生效,之後的請求也不安全。
raise hold_error(connection_id, "The second refresh failed.")
if error_body(response).get("error") == "invalid_grant":
# 已過期、已使用,或連線已終止。再次送出
# 可能會終止連線。
raise hold_error(connection_id, "The refresh returned invalid_grant.")
if response.status_code != 200:
# 保留重新整理權杖的拒絕,因此解除暫停。
save_tokens(connection_id, tokens)
response.raise_for_status()
body = response.json()
tokens = ConnectionTokens(
refresh_token=body["refresh_token"],
access_token=body["access_token"],
expires_at=issued_at + body["expires_in"],
refresh_expires_at=issued_at + body["refresh_token_expires_in"],
)
# 若寫入失敗,請重試寫入。請勿再次重新整理。
for attempt in range(5):
try:
save_tokens(connection_id, tokens)
return tokens.access_token, tokens.expires_at
except OSError: # your secret store's error type
if attempt < 4:
time.sleep(2**attempt)
# 新權杖僅存在於此程序中,且已儲存的重新整理權杖
# 已用掉。儲存的記錄仍處於暫停狀態。錯誤會攜帶新
# 權杖,讓呼叫端能在密鑰儲存庫恢復後儲存它們。
error = hold_error(
connection_id,
"The refresh succeeded, but the new tokens could not be saved.",
)
error.new_tokens = tokens
raise error回應包含新的 access_token 和新的 refresh_token。您傳送的重新整理 token 已被取代:請勿再次傳送它,除非下方的失敗清單另有說明。先前的存取 token 會在幾分鐘內失效。OAuth token 程式碼片段初始化定義了範例所呼叫的函式。
- 在使用新的存取 token 之前,先儲存新的重新整理 token。
- 從單一服務重新整理每個連線的 token,且一次只進行一個重新整理。如果該服務有多個副本,請使用所有副本共用的鎖。已使用過的重新整理 token 若在首次使用後超過 30 秒才再次送達,將會終止連線。所有 token 都會遭撤銷,客戶會顯示為 Unlinked,且在他們再次連結之前,沒有任何憑證可以向他們計費。
- 在您的 HTTP 用戶端和任何代理伺服器中,關閉重新整理請求的自動重試。
如果使用重新整理 token 的第一個請求失敗:
- 請求無法連線:重新整理 token 並未送出。請稍後再試。
- 連線中斷,或收到此清單中
503以外的任何 5xx 回應:您無法得知該請求是否已生效,因此請再傳送一次相同的重新整理 token。- 立即傳送,且僅在距您傳送第一個請求不到 30 秒時才傳送。
- 如果它回傳新的 token,請儲存它們並只使用它們。如果第一個請求確實已生效,其 token(從未送達您手中)會遭撤銷。
- 如果它回傳任何其他結果或沒有回應,或已超過 30 秒,請勿再次傳送該重新整理 token。停止重新整理該連線,並再次連結客戶。
- 逾時:該請求可能仍在執行中。請勿再次傳送該重新整理 token。停止重新整理該連線,並再次連結客戶。
429,或附帶retry-after標頭且主體頂層含有"type": "error"的503:沒有任何項目遭撤銷。至少等待標頭所指示的時間,然後再次傳送相同的重新整理 token。unauthorized_client或invalid_client:沒有任何項目遭撤銷。error_description會說明原因,例如工作區遺失、您的應用程式已不再註冊offline_access,或用戶端斷言失敗。修正後,再次傳送相同的重新整理 token。invalid_scope:請求傳送了scope參數,或您的應用程式已不再註冊billing:attribution。沒有任何項目遭撤銷。修正原因,並再次傳送相同的重新整理 token。invalid_grant:重新整理 token 已過期或已被使用、連線已終止,或客戶的組織已遭停權。停止重新整理該連線,並依照再次連結客戶操作,其第一步是檢查是否遭停權。
如果連線中斷、5xx 回應或逾時使您停止重新整理某個連線,也請暫停您其他連線的重新整理。恢復時,先重新整理一個連線,並僅在該次重新整理成功或收到 4xx 回應後,才恢復其他連線。
在沙箱中執行代理
僅將存取 token 提供給「sandbox」(沙箱),絕不提供重新整理 token。由您的後端進行重新整理,並將每個新的存取 token 傳送至沙箱。後端根據沙箱本身的身分(例如其 pod 身分)決定沙箱服務哪位客戶,絕不根據沙箱傳送的值。後端只會將該客戶的 token 傳送給沙箱。沙箱必須無法取得符合您任何聯合規則或您應用程式用戶端驗證的 JWT。請勿為其掛載身分 token,也不要讓它存取雲端中繼資料伺服器。
Claude Code、Claude Agent SDK 和 Anthropic SDK 可以從組態設定檔中的憑證檔案讀取 token(請參閱設定檔組態檔)。在沙箱中,以此設定檔建立一個組態目錄。請勿在其中加入 client_id:若加入,SDK 會嘗試自行重新整理 token。
{
"version": "1.0",
"authentication": {
"type": "user_oauth"
}
}在代理啟動前以及每次重新整理後,將存取 token 寫入同一目錄中的 credentials/customer.json。expires_at 是以 Unix 秒數表示的到期時間。以模式 0600 寫入新檔案,然後將其重新命名以覆蓋舊檔案:
{
"type": "oauth_token",
"access_token": "sk-ant-oat01-...",
"expires_at": 1793635200
}將 ANTHROPIC_CONFIG_DIR 設為組態目錄,並將 ANTHROPIC_PROFILE 設為 customer。取消設定沙箱中的所有其他憑證,例如 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN、CLAUDE_CODE_OAUTH_TOKEN,以及 Claude Code 的 apiKeyHelper 設定,因為每一項都可能優先於該設定檔。代理會在 expires_at 前的最後 2 分鐘內,以及收到 401 回應後,再次讀取該檔案。
def write_credentials_file(
config_dir: Path, profile: str, token: str, expires_at: int
) -> None:
credentials_dir = config_dir / "credentials"
credentials_dir.mkdir(mode=0o700, parents=True, exist_ok=True)
body = {"type": "oauth_token", "access_token": token, "expires_at": expires_at}
# 將完成的檔案重新命名到定位,讓代理程式永遠不會讀到半個檔案。
# mkstemp 會設定模式 0600 並以目前使用者為擁有者,因此請以
# 代理程式的使用者身分執行。
handle, temporary_path = tempfile.mkstemp(dir=credentials_dir)
with os.fdopen(handle, "w") as temporary_file:
json.dump(body, temporary_file)
os.replace(temporary_path, credentials_dir / f"{profile}.json")再次連結客戶
在以下情況下再次連結客戶:
- 重新整理回傳了
invalid_grant。 - 您遺失了重新整理 token,或 token 外洩。
- 您遺失了步驟 8 中針對
billing:attribution offline_access的回應,或步驟 8 針對此類連線回傳了invalid_grant。 - 重新整理 token 即將到期。
請依照以下步驟操作:
- 在您的 User profiles 頁面上,檢查客戶是否顯示為 Linked。收到
invalid_grant後,請先詢問您的 Anthropic 客戶團隊,客戶的組織是否已遭停權:停權結束後,您持有的重新整理 token 會再次生效。如果所有連線同時回傳invalid_grant,請在取消連結任何人之前,先從您這一方尋找原因,例如工作區已封存。 - 如果客戶顯示為 Linked,請依照取消連結客戶所述取消連結。取消連結會撤銷該連線的 token。請在客戶組織的管理員準備好核准時再執行,因為在他們核准之前,透過該連線的計費會停止。
- 使用客戶現有的使用者設定檔再次執行步驟 5 至 8。以新的連線 ID 和新的 token 取代先前的值並加以儲存。
關閉僅限操作員的驗證
若要阻止僅以您的操作員服務帳戶身分驗證的請求向客戶計費,請開啟 Disable operator-only tokenless authentication(應用程式的 disable_operator_only_auth 設定)。它位於應用程式 Client authentication 分頁上的操作員服務帳戶下方。您的應用程式必須具有 billing:attribution 和 offline_access 範圍以及一個供其 OAuth token 使用的工作區。開啟之前,請確認每位已連結的客戶都已核准 billing:attribution offline_access,且您使用其存取 token 的請求都能正常運作。開啟期間,只有 billing:attribution 連線的存取 token 才能向該連線的客戶計費。僅以服務帳戶身分驗證並設定 bill_to: "user_profile" 的請求會以 403 user_profile_not_billable 遭拒。客戶仍會顯示為 Linked,因此請在您的記錄中留意此錯誤。服務帳戶仍可管理使用者設定檔,並傳送由您付費的請求。您可以再次關閉此設定。
OAuth token 程式碼片段初始化
本節中的範例共用以下設定。它定義了:
- 匯入項目,其中包括
httpx套件 - 您應用程式的用戶端 ID 和用戶端斷言類型
ConnectionTokens,它保存連線的 token、其到期時間,以及其on_hold標記RefreshOnHold,即當重新整理 token 不得再次傳送時refresh_connection()所引發的錯誤:該 token 可能已被使用過,或 token 端點回應了invalid_grant。在您清除已儲存 token 中的on_hold之前(例如在停權結束後),refresh_connection()在之後的每次呼叫中也都會引發此錯誤。當重新整理已成功、僅有您的密鑰儲存區拒絕寫入時,其new_tokens會保存要儲存的 token。client_assertion(),它從ANTHROPIC_IDENTITY_TOKEN_FILE所指定的檔案讀取您身分提供者的 JWT。該 JWT 的aud宣告必須是您應用程式用戶端驗證設定中的 audience。load_tokens()和save_tokens(),由您針對自己的密鑰儲存區撰寫
import json
import os
import tempfile
import threading
import time
from collections import defaultdict
from dataclasses import dataclass, field, replace
from pathlib import Path
import httpx
AUTH = "https://auth.claude.com"
# 註冊您的 OAuth 應用程式後,從 platform.claude.com 複製。
CLIENT_ID = "YOUR_CLIENT_ID"
JWT_BEARER = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
REFRESH_MARGIN_SECONDS = 600
# 在此逾時的重新整理會遺失其新權杖,因此請預留 10 秒等待
# 回應。無法建立的連線會在 2 秒內失敗。
REQUEST_TIMEOUT = httpx.Timeout(10, connect=2)
# 第二個請求必須在第一個之後這麼短的時間內開始,否則就不要送出。
# 該頁面給予 30 秒,但請讓此值低於 REQUEST_TIMEOUT 的讀取逾時:
# 已逾時的請求絕不可再次送出。
SECOND_REQUEST_DEADLINE_SECONDS = 4
@dataclass
class ConnectionTokens:
refresh_token: str = field(repr=False)
access_token: str = field(repr=False)
expires_at: int # the access token's expiry time, in Unix seconds
refresh_expires_at: int # the refresh token's expiry time, in Unix seconds
# True:重新整理權杖可能已被使用。請勿再次送出。
on_hold: bool = False
class RefreshOnHold(Exception):
"""The refresh token might have been used, so a person decides what to do next.
Don't catch this to try again. If new_tokens is set, the refresh succeeded and
only the write failed: store those tokens.
"""
new_tokens: ConnectionTokens | None = None
def client_assertion() -> str:
"""Reads your identity provider's JWT on every call, because its file rotates."""
return Path(os.environ["ANTHROPIC_IDENTITY_TOKEN_FILE"]).read_text().strip()
def load_tokens(connection_id: str) -> ConnectionTokens:
"""Reads the connection's newest tokens from your secret store."""
raise NotImplementedError("Read the tokens from your secret store.")
def save_tokens(connection_id: str, tokens: ConnectionTokens) -> None:
"""Writes the connection's newest tokens to your secret store."""
raise NotImplementedError("Write the tokens to your secret store.")管理您的連線
在 Console 中檢視客戶
除了 OAuth 應用程式頁面之外,您還可以在 Console 的 User profiles 頁面上檢視您所有的使用者設定檔。在該清單以及每個使用者設定檔的詳細資料頁面上,Your spend 是您自己為該使用者設定檔的請求所負擔的成本。這是 Anthropic 套用任何額度之前的成本。這些頁面將連線稱為「link」:具有有效連線的使用者設定檔會顯示 Linked,而連線已終止的使用者設定檔則會顯示 Unlinked。
點擊個別使用者設定檔,即可查看其過去 7、28 或 90 天用量的更詳細檢視。
監控每位客戶的用量
Claude Console 和用量與成本分析 API 都會回報每個使用者設定檔的用量。兩者都會計入由您付費的請求和由您的客戶付費的請求。兩者都不會顯示客戶支付的金額或客戶的費率。
在 Console 中,User profiles 頁面會列出每個使用者設定檔過去 28 天的 Requests、Tokens 和 Your spend。由您的客戶付費的請求會計入該設定檔的 Requests 和 Tokens,但不會增加 Your spend。
請使用 Admin API 憑證呼叫 API,例如具有 org:admin 範圍的 OAuth 存取 token 或 Admin API 金鑰。請勿使用您的操作員服務帳戶(步驟 3)。其聯合規則預設授予的是 workspace:developer,而非 org:admin。org:admin 範圍涵蓋整個 Admin API,因此請勿將其新增至操作員服務帳戶。
若要透過 API 依使用者設定檔產生報告,請呼叫其用量端點或成本端點。若要讓每個使用者設定檔各有一列,請僅依 user_profile_id 分組,並省略 time_bucket_width。只有在您請求的時間範圍內有用量的使用者設定檔才會有一列。另外還有一列的 user_profile_id 為 null。它包含未指定任何設定檔的用量,以及在請求之外計量的用量,例如程式碼執行容器時間。
在成本端點上,由您的客戶付費的請求會在 amount 中增加 0,並在 list_amount 中增加其牌價。amount 欄位與 Your spend 是相同的度量。API 沒有用來表示由誰付費的欄位、篩選條件或 group_by[] 值。amount 為 0 且 list_amount 大於 0 的列,通常表示該列中的每個請求都由客戶付費。
請勿使用這些數據在您選定的金額停止客戶的用量。Console 和 API 都不是即時回報。Console 的數據大約每小時更新一次,而請求可能需要數小時才會出現。關於 API 的延遲,請參閱資料新鮮度。支出上限說明了客戶自己的限制有何作用。
取消連結客戶
若要在 Console 中取消連結客戶,請使用 User profiles 頁面上的清單,或使用者設定檔詳細資料頁面右上角的 Unlink 按鈕。
若要從您的後端取消連結客戶,請將您在步驟 8 中儲存的連線 ID 傳送至撤銷端點,並使用與代碼交換相同的用戶端驗證。若要改以使用者設定檔指定連線,請傳送 user_profile_id 以取代 connection_id。
def revoke_connection(connection_id: str) -> list[str]:
response = httpx.post(
f"{AUTH}/v1/oauth/revoke",
json={
"connection_id": connection_id,
"client_id": CLIENT_ID,
"client_assertion_type": JWT_BEARER,
"client_assertion": client_assertion(),
},
)
response.raise_for_status()
# 此請求所終止連線的 ID。若連線已終止
# 或 ID 不明,則清單為空。
return response.json()["revoked_connection_ids"]auth.claude.com 會回應 HTTP 200 和 revoked_connection_ids,即此請求所終止之連線的 ID。如果連線已經終止,清單會是空的,因此您可以安全地重複傳送帶有 connection_id 的請求。如果 ID 不明,清單也會是空的,因此空清單並不能證明該連線曾經存在。關於其他參數,請參閱撤銷;另請參閱撤銷端點的錯誤。
連線終止後,使用者設定檔會顯示為 Unlinked,而針對此客戶設定 bill_to: "user_profile" 的請求會收到 user_profile_not_billable。您仍可透過 bill_to: "self",自行負擔成本為該客戶提供服務。連結之後說明了您的客戶會看到什麼,而關於連結與取消連結的電子郵件說明了哪種取消連結方式會寄送電子郵件給他們。
將客戶連結到其他 Claude 組織
若要將客戶的使用者設定檔連結到其他 Claude 組織,請先取消連結該客戶,然後再次連結。
取消連結後,您向此客戶計費的請求會遭到拒絕。此情況會持續到使用者針對另一個組織進行核准,且您在步驟 8 中交換代碼為止。當該使用者準備好核准時,請依照以下步驟操作:
- 如果您的客戶已在其 Linked platforms 頁面上取消連結您的應用程式,請略過此步驟。否則,請依照取消連結客戶所述取消連結該客戶。之後,該使用者設定檔會在您的 User profiles 頁面上顯示為 Unlinked。
- 使用相同的使用者設定檔再次執行步驟 5 至 8。在步驟 7 中,使用者需要一個在另一個組織中具有管理員或帳單角色的帳戶。請讓使用者針對該組織進行核准。
- 以新的連線 ID 取代先前的值並加以儲存。如果您使用連線的 token,也請以相同方式處理新的 token。
在該客戶的連結遭到取消之前,核准頁面只允許使用者針對已連結的組織進行核准。
支出上限屬於某個客戶組織與您的應用程式,因此第一個組織的上限不會延續。支出上限說明了相關規則。
預期的錯誤
當請求設定 bill_to: "user_profile" 時,Anthropic 會向您的客戶計費或拒絕該請求。它絕不會在未告知的情況下改為向您計費。在 /v1/messages 上,下列清單中的代碼位於 error.details.error_code。在 /v1/chat/completions 上,您會以 OpenAI 格式收到相同的 HTTP 狀態和訊息,但不含代碼:
403 permission_error, user_profile_not_billable:Anthropic 無法就此請求向該客戶計費,且回應中不會說明原因。不可重試,但新連線建立後的前 10 秒內除外。在要求客戶再次連結之前,請參閱user_profile_not_billable的原因:再次連結只能解決其中部分原因。您仍可透過以bill_to: "self"重新傳送,自行負擔成本為該客戶提供服務。在 Anthropic SDK 中,請透過 403 狀態的錯誤類別處理user_profile_not_billable,也就是PermissionDeniedError。這也會符合其他 403 錯誤,因此請一併檢查錯誤代碼。402 billing_error, linked_organization_billing_unavailable:Anthropic 目前無法向客戶的組織計費(例如,該組織已被停權,或其額度在 Claude 開始回覆之後用盡)。回應中不會說明原因。請求送達時已無額度的客戶,則會改為收到linked_organization_spend_limit_reached。不可重試。請告知客戶檢查其 Claude Platform 帳戶。您仍可透過以bill_to: "self"重新傳送,自行負擔成本為他們提供服務。402 billing_error, linked_organization_spend_limit_reached:客戶的組織已達到其自行設定的支出限制。該限制可能是適用於您應用程式的支出上限,也可能是整個組織的每月支出限制。當組織沒有可支付該請求的額度時,Claude API 也會傳送相同的代碼。回應中不會說明是哪一種。該請求在 Claude 開始回覆之前即遭拒絕。不可重試。您仍可透過以bill_to: "self"重新傳送,自行負擔成本為該客戶提供服務。請客戶在 Claude Console 中檢查以下項目:- 您應用程式的支出上限:在 Linked platforms 下您應用程式的頁面中,客戶可以設定或提高支出上限。在該處設定的上限會取代其為所有已連結平台設定的任何預設上限。
- 組織的每月支出上限:在支出限額下,客戶可以提高此上限。
- 額度餘額: 在其帳單頁面上,客戶可以查看其額度餘額並購買額度。有些額度無法支付這些請求:請參閱哪些額度可以付款。
503 overloaded_error:Anthropic 目前無法確認是否能向客戶計費。請使用退避機制重試,並遵循retry-after標頭。該請求未被處理,也未被計費。400 invalid_request_error, user_profile_required:您在未附上anthropic-user-profile-id標頭的情況下設定了bill_to: "user_profile"。此類請求需要該標頭,除非它使用連線的存取 token 且該標頭為選用。若要確認該標頭是否為選用,請參閱使用連線的存取 token 呼叫 Claude 中的附註。400 invalid_request_error,不含錯誤代碼:anthropic-user-profile-id標頭所含的 ID 格式錯誤,或不是您組織的使用者設定檔。400 invalid_request_error,不含錯誤代碼:請求以連線的存取 token 進行驗證,且設定了bill_to: "self",或指定了該 token 所限定之使用者設定檔以外的使用者設定檔。請參閱使用連線的存取 token 呼叫 Claude。
在 /v1/messages 和 /v1/chat/completions 上,連線的存取 token 無法傳送由您付費的請求。若要以 bill_to: "self" 重新傳送遭拒的請求,請從您自己的後端,以您操作員服務帳戶自己的憑證進行驗證。使用連線的存取 token 呼叫 Claude 列出了該 token 本身會遭到的拒絕。
成功的回應不會說明向誰計費,因此請自行記錄您以 bill_to: "user_profile" 傳送了哪些請求。
user_profile_not_billable 的原因
請依序檢查以下項目:
- 您的請求。 請求必須以您 OAuth 應用程式的操作員服務帳戶身分進行驗證(步驟 3)。連線的存取 token 也是以該服務帳戶身分進行驗證。以任何其他方式驗證的請求都會被拒絕,例如以其他服務帳戶身分驗證,或使用未綁定至該服務帳戶的 API 金鑰。如果
anthropic-user-profile-id標頭指定的是您其中一個未連結的設定檔,請求會被拒絕。如果憑證或標頭有誤,請修正請求。建立新連線並無幫助。 - 連線。 客戶尚未透過此應用程式連結,或連線已終止:由其組織或您組織的管理員終止,或由您的後端終止。已終止的連線會在您的 User profiles 頁面上顯示為 Unlinked。僅透過您的測試應用程式連結的設定檔,並未連結到您的正式應用程式。在客戶連結之前,請停止向該客戶計費。連線的存取 token 僅限於該連線,因此在客戶再次連結後,請使用新連線的存取 token。如果您的應用程式已關閉僅限操作員的驗證,您只能使用客戶連線的存取 token 向其計費。此時,若您未持有某位客戶任何有效的
billing:attribution連線 token,該客戶雖然會顯示為 Linked,但必須依照再次連結客戶所述再次核准。 - 客戶的組織。 它必須是符合資格的客戶。您無法從您這一方得知這一點,因此請詢問您的 Anthropic 客戶團隊。
新連線通常會立即生效,但在步驟 8 的交換之後可能需要約 10 秒。如果請求在這 10 秒內以 user_profile_not_billable 遭到拒絕,請再次傳送。在那之後,等待或重試都不會改變結果。請記錄每個遭拒請求的完整 error.message 和 request-id 回應標頭。如果連線顯示為 Linked 的客戶仍遭拒絕,且您的請求正確無誤,請將遭拒請求的 request-id 傳送給您的 Anthropic 客戶團隊,讓 Anthropic 能查明其遭拒原因。
您客戶的視角
連結
您的應用程式在步驟 6 將使用者重新導向後,使用者會在 auth.claude.com 上進行核准。步驟 7 列出了核准頁面的各個畫面。每個畫面都會顯示您應用程式的名稱,並有一個 Cancel 按鈕。使用者在每個畫面上的操作如下:
- Select an organization:使用者選擇要連結自己的哪一個 Claude 組織。只有在使用者有多個組織可選擇時,頁面才會顯示此畫面。
- How billing works:使用者閱讀該畫面並點擊 Continue。
- Set a monthly spend limit:使用者以整數美元為您的應用程式輸入限額並點擊 Continue。金額欄位一開始為空白,因此頁面不會替使用者選擇限額。Continue without a limit 不會儲存新的限額,且客戶先前儲存的上限或預設值仍然適用。使用者輸入的限額即為支出上限所說明的支出上限。當您的應用程式處於測試階段時,此畫面會有所不同:請參閱當您的應用程式處於測試階段時。
- 最後一個畫面:此畫面列出您的應用程式將能執行的操作,包括使用者所選擇的限額。使用者點擊 Link and authorize。
核准頁面會使用瀏覽器中目前登入的 Claude 帳戶,且只會提供該帳戶的 Claude 組織。該帳戶可能不是您的使用者預期的帳戶,例如是個人帳戶而非工作帳戶。您的應用程式無法選擇帳戶。OpenID Connect 參數 prompt=select_account 和 login_hint 不會改變頁面所使用的帳戶。
連結之後
您的客戶在 Claude Console 的 Linked platforms 頁面上管理其連線。他們可以隨時取消連結您的應用程式。他們這麼做時,Anthropic 不會通知您:您不會收到任何 webhook 事件,也不會收到電子郵件。
客戶取消連結後,您向該客戶計費的請求會以 403 user_profile_not_billable 遭到拒絕(請參閱 user_profile_not_billable 的原因)。該客戶的使用者設定檔會在 Console 中您的 User profiles 頁面上顯示為 Unlinked。若要再次連結,請使用客戶現有的使用者設定檔再次執行步驟 5 至 8。
關於連結與取消連結的電子郵件
Anthropic 關於連結與取消連結的電子郵件,會寄送給您客戶組織中具有管理員或帳單角色的成員。每封電子郵件都會連結至客戶的 Linked platforms 頁面。Anthropic 是否寄送電子郵件取決於事件:
- 客戶連結您的應用程式時: 當您在步驟 8 中交換代碼時,Anthropic 會寄送電子郵件。對於您從未交換其代碼的核准,則不會寄送任何內容。當客戶仍處於連結狀態而使用者再次核准時,也不會寄送任何內容。
- 客戶取消連結您的應用程式時: Anthropic 會寄送電子郵件。其中不會指明是誰取消連結了您的應用程式。
- 您從後端取消連結客戶時: Anthropic 會寄送電子郵件。
- 您在 Console 中取消連結客戶時: Anthropic 不會寄送電子郵件。
Anthropic 不保證電子郵件一定會寄出或送達。當您取消連結客戶時,請您自行告知客戶。請勿依賴這些電子郵件來告知客戶他們已完成連結。
支出上限
您的客戶可以為您的應用程式設定以美元(USD)計價的每月支出上限。核准頁面將此上限稱為每月支出限制,而進行連結的使用者可以在該處設定(請參閱連結)。它與組織的每月支出上限是分開的,後者適用於整個組織。您無法讀取客戶的上限,也無法得知他們已使用了多少。
當客戶透過您應用程式的支出達到上限時,Claude API 會以 402 拒絕您向他們計費的請求。請參閱預期的錯誤。拒絕會持續到下個月第一天的 00:00 UTC,或直到客戶提高或移除上限為止。對上限的變更大約需要一分鐘才會生效。
連結之後,客戶組織中具有管理員或帳單角色的成員會在 Console 的 Linked platforms 頁面上管理上限:
- 設定或變更上限: 點擊您的應用程式,然後點擊 Set spend cap 或 Edit spend cap。
- 設定預設值: 在 Default spend cap 下,點擊 Set default 或 Edit。每個沒有自己上限的已連結應用程式,每月最多可支出至預設值。各應用程式不會共用此額度。
- 移除上限: 點擊您的應用程式、Edit spend cap,然後點擊 Remove cap。之後您的應用程式會使用預設值。如果沒有預設值,您的應用程式就沒有上限。
最小的上限為 $0 USD,這會拒絕您向該客戶計費的每個請求。Console 接受整數美元金額,實際上沒有最大值。上限會以牌價計算 token 成本和網頁搜尋費用,且未計入任何議定折扣。客戶的帳單金額可能與上限所計算的金額不同。
上限可以高於組織的每月支出上限,後者由客戶在支出限額下設定。達到其中任一項時,Claude API 都會拒絕您向該客戶計費的請求。
當您的應用程式處於測試階段時
每當有人在應用程式處於測試中、審核中或未獲核准的狀態時連結您的應用程式或變更其上限,都適用以下限制:
| 測試中、審核中或未獲核准 | 應用程式上線後 | |
|---|---|---|
| 核准頁面上的每月支出限制 | 必填,$50 USD 以下 | 選填 |
| 核准頁面上的金額欄位 | 一開始為 $50 USD | 一開始為空白 |
| 核准頁面上的 Continue without a limit | 不提供 | 提供 |
| 在 Console 中移除上限 | 無法 | 可以 |
| 客戶可設定的最大上限 | $50 USD | 實際上沒有最大值 |
您的應用程式上線後,客戶在此之前儲存的上限會保持不變。之後客戶可以提高或移除該上限。
支援您的客戶
您需要為客戶提供與您的應用程式相關的所有支援,包括您向他們計費的 Claude 用量。Anthropic 會在 Claude Console 中為您的客戶提供核准頁面和 Linked platforms 頁面。在 Linked platforms 頁面上,具有管理員或帳單角色的成員可以查看您的應用程式本月為該組織產生的費用。他們也可以為您的應用程式設定每月支出上限,以及取消連結您的應用程式。所有其他關於您應用程式的問題都應該向您提出,因此請告訴您的客戶如何與您聯繫。
程式碼片段初始化
本頁的 Python 範例共用以下設定,您只需撰寫一次。它定義了:
- 匯入項目
- 您應用程式的用戶端 ID 和重新導向 URI
- 計費 beta 標頭值
- 一個以您的服務帳戶身分進行驗證的 Claude API 用戶端
client_assertion,它會回傳您的後端傳送至auth.claude.com的用戶端斷言
# Python 範例假設已有以下初始化與變數
import secrets
from urllib.parse import urlencode
import anthropic
import httpx
from anthropic.lib.credentials import IdentityTokenFile
from anthropic.types import Message
from anthropic.types.beta import BetaMessage
from authlib.oauth2.rfc7636 import create_s256_code_challenge
AUTH = "https://auth.claude.com"
# 在您註冊 OAuth 應用程式後,從 platform.claude.com 複製。
CLIENT_ID = "YOUR_CLIENT_ID"
REDIRECT_URI = "https://app.example.com/claude/billing/callback"
JWT_BEARER = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
BILLING_BETA = "user-profiles-billing-2026-10-01"
# API 用戶端。SDK 會將您工作負載的身分 JWT 交換為存取
# 權杖並負責重新整理,因此您無須自行處理 "Bearer <access token>"。
client = anthropic.Anthropic()
# auth.claude.com 的用戶端斷言:即身分 JWT 本身,每次呼叫時
# 重新讀取,因為該檔案會輪替。若您應用程式的用戶端驗證
# 設定所指定的 audience 與您的聯合規則不同,請將此處指向
# 第二個權杖檔案:IdentityTokenFile("/path/to/other/token")。
client_assertion = IdentityTokenFile()這個頁面有幫助嗎?