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です。登録によってメールやFAXの送信、支払いが発生することはありません。

対応する登録方式：anonymous・service_auth。資格情報：identity_assertion・Bearer access_token。アカウント所有者はSingleFaxにログインし、要求された権限を確認して、エージェントから提示された6桁のコードを入力します。対応スコープはfax:read、fax:draft、fax:send、inbox:read、credits:read、credits:checkoutです。初期の権限はfax:readとcredits:readです。追加スコープは明示的に要求してください。

  1. 所有者がhttps://singlefax.com/dashboard/agent-accessにログインし、エージェント名と許可する権限を選び、登録用トークンを明示的に作成します。この短期のシークレットは一度だけ表示され、10分で失効し、1つのエージェントの登録にのみ使えます。対象エージェントに渡してください。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、有効期限、claimが返り、user_code、verification_uri、5秒のポーリング間隔が含まれます。承認前にアサーションは発行されません。
  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に追加しないでください。登録を許可した確認済みアカウントだけが承認できます。名前は所有者が決めたもので、要求スコープは縮小できますが、登録時に許可した範囲は超えられません。メールのヒントと関連付け用メールは、登録を許可した所有者と一致する必要があります。ユーザーは拒否できます。関連付けは10分で失効し、新しい試行を開始すると古いリンクは無効になります。アカウントは自動作成されません。
  5. POST https://api.singlefax.com/api/auth/oauth2/tokenに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を指定してポーリングします。authorization_pending、slow_down（間隔を5秒増やす）、expired_token、access_deniedに対応してください。承認されると、不透明なaccess_token、token_type、expires_in、scope、identity_assertion、assertion_expiresが返ります。関連付け前のトークンとアサーションは、承認時に無効になります。
  6. 許可されたスコープで、MCPまたはA2AにAuthorization: Bearer <access_token>を使用します。トークンの有効期間は最大1時間です。更新には同じトークンエンドポイントに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. トークン1件の取り消しは、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レプリカにまたがって所有者ごとに制限され、有効で未使用のトークンは最大5件です。登録許可のない公開リクエストは、所有者の登録枠を消費しません。トークンがない場合は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、WWW-Authenticateが参照するURL）を記述します。どちらにも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を渡し、その後create_fax_draftにtoとuploadTokenを指定します。base64はごく小さいファイル専用です。uploadUrlへのPUTはパス内の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. データパートを1つ送ります：{ "skill": "<skill id from the card>", "arguments": { ... } }。自由記述のテキストは解釈しません。
  3. FAX・番号のスキルは、Stripe Checkoutへのリンク（checkoutUrl）を返します。A2Aはアカウントのクレジットやプランのページ数枠を消費しません。支払い待ちの下書きはタスク状態input-requiredです。GetTaskでポーリングしてください。

AP2でクレジットを購入するにはcredits:checkoutを要求し、マーチャント拡張をネゴシエートしてください。署名付きカート・支払い委任、所有者の別途のパスキー承認、Stripe Shared Payment Tokenの利用、台帳で確認済みの領収書については、https://singlefax.com/ap2.mdで説明しています。

GetTaskにfax:readを指定すると、FAX下書きでは送信状況を、番号の購入では決済と番号割り当てを追跡します。番号のタスクは番号が有効になると完了します。クレジットの購入には、注文に関連付けられたポーリング対象のタスクはありません。お支払い後に残高を確認してください。

方式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を省略し、期限付き・1回限りのenrollmentTokenを受け取る方法もあります。その後ホストがPOST https://api.singlefax.com/api/auth/host/enrollに{ "token": <enrollment token>, "public_key": <host public JWK>, "name": "My agent host" }を指定します。ブラウザーの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です。POST https://api.singlefax.com/api/auth/capability/executeにAuthorization: Bearer <signed agent+jwt>と{ "capability": "get_credits", "arguments": {} }を指定するか、他の許可済み機能にドキュメント記載の引数を渡してください。これらの資格情報は署名された証明であり、APIキーやOAuthアクセストークンではありません。
  6. 登録済みエージェントの新しいデバイスコードは、POST https://api.singlefax.com/api/auth/agent/device/codeに{ "agent_id": "<registered id>" }と署名済みホストJWTを指定して取得します。このエンドポイントではエージェントを登録できません。取り消しにはPOST https://api.singlefax.com/api/auth/agent/revokeに{ "agent_id": "<registered id>" }と、所有ホストのJWTまたは所有者のセッションを指定します。send_faxにはパスキーによる本人確認が必要で、自律実行はできません。

ここにID-JAGや{ "type": "anonymous" }をPOSTしてはいけません。これらのID形式には対応していません。

機械による支払い（OAuthとは別）

自律的な支払いは、POST /api/v1/machine/faxesのMPP HTTP 402でStripe Shared Payment TokenまたはTempo USDCを使います。https://singlefax.com/mpp.mdをご覧ください。CursorはSPTを発行できないため、/mcpではなくそのREST URLに対してStripe Link CLIを使用してください。Tempoウォレットは同じURLのTempoチャレンジで支払います。

HIPAA

MCP、MPP、公開APIでPHIを送信しないでください。HIPAAの対象機関は、電子BAA付きのウェブサイトのHIPAA Secureモードを利用してください。