singlefax
語言

SingleFax 驗證文件

API 金鑰、MCP 適用的 OAuth 及委派 Agent Auth。

AI 代理與開發者驗證指南。

代理如何向 SingleFax 驗證身分。HTML 安裝頁：https://singlefax.com/agents

本檔案是 /.well-known/oauth-authorization-server 的 RFC 8414 中繼資料所公布的 agent_auth.skill 目標。

SingleFax 支援 Auth.md anonymous 及 service_auth 註冊，搭配使用者核准及服務簽署的身分聲明。匿名憑證在核准前無法存取帳戶。不接受外部供應商 ID-JAG。舊版 Better Auth 主機／代理 JWT 流程另見路徑 C。

Auth.md 註冊與權杖交換

適用對象：註冊以代表既有 SingleFax 帳戶操作的 AI 代理。所有註冊方式均須帳戶擁有者核發註冊許可。 未附有效註冊權杖的公開請求，會在建立註冊前遭拒。OAuth 發行者為 https://api.singlefax.com/api/auth，資源為 https://singlefax.com/mcp。註冊不會寄信、傳真或收費。

支援註冊方式：anonymous、service_auth。憑證：identity_assertion 及 Bearer access_token。擁有者登入 SingleFax，審核要求權限並輸入代理的六位數代碼。支援範圍為 fax:read、fax:draft、fax:send、inbox:read、credits:read、credits:checkout。預設權限為 fax:read、credits:read，其他範圍須明確要求。

  1. 擁有者登入 https://singlefax.com/dashboard/agent-access，選擇代理名稱及權限，明確建立註冊權杖。此短效密鑰僅顯示一次，十分鐘到期，只能註冊一個代理。請交給該代理。API 佈建使用擁有者第一方瀏覽器工作階段，在 POST https://singlefax.com/api/auth/agent/identity/manage 搭配 { "action": "enroll", "name": "My agent", "scopes": ["fax:read", "credits:read"] }。絕不與代理分享瀏覽器 Cookie。未使用權杖可於同頁撤銷。
  2. 使用 POST https://api.singlefax.com/api/auth/agent/identity，搭配 Content-Type: application/json、{ "type": "service_auth", "enrollment_token": "<owner-issued token>", "login_hint": "<enrolling owner email>" } 註冊。回傳 registration_id、秘密 claim_token、到期時間，以及含 user_code、verification_uri 與五秒輪詢間隔的 claim。核准前不核發聲明。
  3. 或以 { "type": "anonymous", "enrollment_token": "<owner-issued token>" } 註冊。此處匿名指認領前憑證，不是開放公開註冊。會立即回傳簽署的 identity_assertion 及 claim_token。交換認領前聲明只能取得空白權限權杖，無法存取任何帳戶。使用 POST https://api.singlefax.com/api/auth/agent/identity/claim 搭配 { "claim_token": "<secret>", "email": "<account email>" } 開始核准，並讀取回傳的 claim_attempt。
  4. 另外顯示代碼，為使用者開啟 verification_uri。URL 內含秘密認領嘗試權杖，不要將代碼加入 URL。只有發起註冊且已驗證的帳戶可核准。名稱由擁有者固定；權限可縮減，但不得超出註冊許可。信箱提示及認領信箱須符合發起註冊者。使用者可拒絕。認領十分鐘到期，新嘗試會使舊連結失效，不會自動建立帳戶。
  5. 以 Content-Type: application/x-www-form-urlencoded、grant_type=urn:workos:agent-auth:grant-type:claim&claim_token=<secret>&resource=https%3A%2F%2Fsinglefax.com%2Fmcp 輪詢 POST https://api.singlefax.com/api/auth/oauth2/token。處理 authorization_pending、slow_down（間隔增加五秒）、expired_token、access_denied。核准回傳不透明 access_token、token_type、expires_in、scope、identity_assertion、assertion_expires。認領前權杖與聲明於核准時失效。
  6. 在 MCP 或 A2A 使用 Authorization: Bearer <access_token> 及已授權範圍。權杖最長一小時；更新時在同一端點使用 grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=<identity_assertion>&resource=https%3A%2F%2Fsinglefax.com%2Fmcp，不發更新權杖。除非撤銷註冊，聲明最多 30 天可重新交換。EdDSA 簽章使用發行者的 /jwks；typ 為 oauth-id-jag+jwt，iss/aud 均等於發行者。
  7. 以 POST https://api.singlefax.com/api/auth/oauth2/revoke、表單主體 token=<access_token>&token_type_hint=access_token 撤銷單一權杖。此操作具冪等性，聲明仍可使用。以 POST https://api.singlefax.com/api/auth/agent/identity/revoke、JSON { "identity_assertion": "<identity_assertion>" } 撤銷註冊，所有存取權杖及後續交換將停止。

擁有者可在 https://singlefax.com/dashboard/agent-access 檢視並撤銷授權。撤銷註冊會停止相關存取權杖及聲明更新。

認領及核准回應屬私人資料，絕不可快取。認領權杖、聲明及存取權杖須保密。註冊許可核發在所有 API 副本間按擁有者限流，同時最多五個有效未使用權杖。無許可的公開請求不消耗擁有者註冊額度。缺少權杖回傳 enrollment_required；過期、撤銷或已用回傳 invalid_enrollment。註冊失敗不消耗註冊權杖。被動就緒掃描不得探測註冊端點。

探索

資源伺服器（MCP + API BFF）：https://singlefax.com

GET https://singlefax.com/.well-known/oauth-protected-resource
GET https://singlefax.com/.well-known/oauth-protected-resource/mcp

受保護資源中繼資料（RFC 9728）：根文件描述來源（resource https://singlefax.com）；/.well-known/oauth-protected-resource/mcp 描述 MCP 伺服器（resource https://singlefax.com/mcp，即 URL WWW-Authenticate 指向的位置）。兩者均列出 authorization_servers（發行者 https://api.singlefax.com/api/auth）及 scopes_supported。請為 https://singlefax.com/mcp 申請權杖。

GET https://singlefax.com/.well-known/oauth-authorization-server
GET https://singlefax.com/.well-known/oauth-authorization-server/api/auth

授權伺服器中繼資料包含 issuer、authorization_endpoint、token_endpoint、registration_endpoint、jwks_uri、scopes_supported、agent_auth（skill 指向本頁）。

API 來源 https://api.singlefax.com 提供相同 well-known 文件。

路徑 A：MCP OAuth（聊天應用程式）

Cursor、Claude、ChatGPT、Codex、VS Code 使用此路徑。

  1. 加入 MCP https://singlefax.com/mcp（Streamable HTTP）。
  2. 收到 401 時，讀取 WWW-Authenticate 並取得上述 PRM。
  3. 動態用戶端註冊：POST {issuer}/oauth2/register（PKCE S256，公開用戶端使用 token_endpoint_auth_method=none）。
  4. 於 {issuer}/oauth2/authorize 進行授權碼 + PKCE。
  5. 於 {issuer}/oauth2/token 取得權杖。
  6. POST /mcp 搭配 Authorization: Bearer。一般文件先呼叫 create_upload，給使用者 uploadPageUrl，再以 to、uploadToken 呼叫 create_fax_draft。base64 僅適合極小檔案。PUT 至 uploadUrl 使用路徑內的 HMAC 權杖，不加 OAuth 標頭。傳送原始 Word、Excel、PDF 或圖片，不要先轉 PDF。

權限範圍：openid、profile、email、offline_access、fax:read、fax:draft、fax:send、inbox:read、credits:read、credits:checkout。AP2 購買額度須明確要求 credits:checkout；每筆扣款仍須另行通行金鑰核准。

未驗證的 POST /mcp 僅接受 server/discover；initialize、tools/list、tools/call 需要 OAuth。

路徑 A2：A2A（代理對代理）

代理卡：GET https://singlefax.com/.well-known/agent-card.json（A2A 1.0）。端點：POST https://singlefax.com/a2a（JSON-RPC：SendMessage、GetTask、CancelTask；亦支援 0.3 名稱 message/send、tasks/get、tasks/cancel）。

  1. 使用與路徑 A 相同的 OAuth 伺服器、權限及權杖（要求資源 https://singlefax.com/mcp），傳送 Authorization: Bearer。/a2a 不接受綁定 DPoP 的權杖。
  2. 傳送單一資料部分：{ "skill": "<skill id from the card>", "arguments": { ... } }，不解讀自由文字。
  3. 傳真及號碼技能回傳 Stripe Checkout 連結（checkoutUrl）。A2A 絕不花用帳戶餘額或方案頁數。等待付款草稿的任務狀態為 input-required，以 GetTask 輪詢。

AP2 購買額度請要求 credits:checkout 並協商商家擴充。簽署購物車與付款授權、擁有者獨立通行金鑰核准、Stripe Shared Payment Token 兌付及帳本確認收據，見 https://singlefax.com/ap2.md。

GetTask 搭配 fax:read，對傳真草稿追蹤送達，對號碼結帳追蹤付款與佈建。號碼啟用即完成任務。額度包結帳沒有可輪詢的訂單任務，請付款後查餘額。

路徑 B：API 金鑰（後端與 CLI）

  1. 至 https://singlefax.com/dashboard/api-keys 建立金鑰（sf_live_…）。
  2. 購買預付額度。
  3. 在 https://singlefax.com/api/v1/…（或 https://api.singlefax.com/api/v1/…）使用 Authorization: Bearer sf_live_…。
  4. CLI：npx @singlefax/cli send FILE --to +E164 搭配 SINGLEFAX_API_KEY。傳入原始 Word、Excel、PDF 或圖片，不要先轉 PDF。

語言範例（curl、Node、Python、Go、PHP）：https://singlefax.com/developers.md

OpenAPI：https://singlefax.com/openapi.json

路徑 C：Better Auth 委派主機／代理 JWT

委派能力（validate_fax、send_fax、get_fax_status、get_credits、create_credit_checkout）採裝置核准。

  1. 讀取 GET https://api.singlefax.com/.well-known/agent-configuration 了解演算法、端點、模式及核准方式。Agent Auth 發行者為 https://api.singlefax.com，與結尾為 /api/auth 的 OAuth 發行者不同。使用此來源作 JWT audience。以支援演算法分別產生主機與代理簽署金鑰，私鑰務必保密。
  2. 先佈建主機。 已停用動態主機註冊。擁有者必須登入 SingleFax，以第一方瀏覽器工作階段呼叫 POST https://singlefax.com/api/auth/host/create（API 等效來源：https://api.singlefax.com/api/auth/host/create），提供 { "name": "My agent host", "public_key": <host public JWK>, "default_capabilities": [] }。回應的 hostId 識別已註冊主機。空白預設確保能力需要另行核准。或省略 public_key，取得有期限的一次性 enrollmentToken，主機再以 { "token": <enrollment token>, "public_key": <host public JWK>, "name": "My agent host" } 呼叫 POST https://api.singlefax.com/api/auth/host/enroll。絕不與代理分享瀏覽器 Cookie 或私有簽署金鑰。
  3. 在 POST https://api.singlefax.com/api/auth/agent/register 註冊，傳送 Authorization: Bearer <signed host+jwt> 及 JSON { "name": "My agent", "mode": "delegated", "capabilities": ["validate_fax", "get_fax_status", "get_credits"], "preferred_method": "device_authorization", "force_approval": true }。JWT 標頭使用 typ: "host+jwt"、支援的 alg，以及簽署 JWK 若有提供的 kid。宣告包含 iss: <registered hostId>、aud: "https://api.singlefax.com"、全新 jti、目前 iat、60 秒內的 exp 及 agent_public_key: <agent public JWK>。以已佈建主機金鑰簽署。重複 JWT 識別碼會遭拒。
  4. 註冊回傳 agent_id、host_id、狀態、能力授權及必要時的 approval 物件。顯示裝置代碼並開啟 SingleFax 的 verification_uri_complete。使用者在回傳的驗證 URL 登入核准。註冊、佈建及核准會改變帳戶狀態；被動掃描器只能讀取探索文件。
  5. 使用新主機 JWT（iss: <host_id>）輪詢 GET https://api.singlefax.com/api/auth/agent/status?agent_id=<registered id>。核准後以代理私鑰簽代理 JWT：標頭 typ: "agent+jwt"，支援的 alg/kid；宣告 iss: <host_id>、sub: <agent_id>、aud: "https://api.singlefax.com"、目前 iat、60 秒內 exp 及全新 jti。以 Authorization: Bearer <signed agent+jwt>、{ "capability": "get_credits", "arguments": {} } 呼叫 POST https://api.singlefax.com/api/auth/capability/execute，或按文件參數使用其他已授權能力。這些憑證是簽署證明，不是 API 金鑰或 OAuth 存取權杖。
  6. 已註冊代理若需新裝置代碼，以 { "agent_id": "<registered id>" } 及簽署主機 JWT 呼叫 POST https://api.singlefax.com/api/auth/agent/device/code。此端點不能註冊代理。以 POST https://api.singlefax.com/api/auth/agent/revoke、{ "agent_id": "<registered id>" } 及擁有主機 JWT 或擁有者工作階段撤銷。send_fax 需要使用者以通行金鑰驗證，不能自主執行。

不要在此 POST ID-JAG 或 { "type": "anonymous" }，不支援這些身分類型。

機器付款（不是 OAuth）

自主付款透過 POST /api/v1/machine/faxes 的 MPP HTTP 402，搭配 Stripe Shared Payment Token 或 Tempo USDC。見 https://singlefax.com/mpp.md。Cursor 無法產生 SPT；請讓 Stripe Link CLI 呼叫該 REST URL，而不是 /mcp。Tempo 錢包支付相同 URL 的 Tempo 挑戰。

HIPAA

勿透過 MCP、MPP 或公開 API 傳送 PHI。適用機構使用網站 HIPAA Secure 模式及電子 BAA。