singlefax
Sprache

SingleFax-Authentifizierungsdokumentation

API-Schlüssel, OAuth für MCP und delegierte Agent Auth.

Authentifizierungsanleitung für KI-Agenten und Entwickler.

So authentifizieren sich Agenten bei SingleFax. HTML-Installation: https://singlefax.com/agents

Diese Datei ist das agent_auth.skill-Ziel, das die RFC-8414-Metadaten unter /.well-known/oauth-authorization-server angeben.

SingleFax unterstützt die Auth.md-Registrierung über anonymous und service_auth mit Nutzerzustimmung und vom Dienst signierten Identitätsnachweisen. Anonyme Zugangsdaten haben vor Genehmigung keinen Kontozugriff. ID-JAGs externer Anbieter werden nicht akzeptiert. Der ältere Better-Auth-Host-/Agent-JWT-Ablauf ist separat unter Weg C dokumentiert.

Auth.md-Registrierung und Tokenaustausch

Zielgruppe: KI-Agenten, die für ein bestehendes SingleFax-Konto handeln sollen. Für jede Registrierungsmethode ist eine vom Kontoinhaber ausgestellte Registrierungsfreigabe erforderlich. Öffentliche Anfragen ohne gültigen Enrollment-Token werden vor Erstellung einer Registrierung abgewiesen. OAuth-Aussteller: https://api.singlefax.com/api/auth; Ressource: https://singlefax.com/mcp. Die Registrierung sendet weder E-Mails noch Faxe und belastet kein Zahlungsmittel.

Unterstützte Methoden: anonymous und service_auth. Zugangsdaten: identity_assertion und Bearer access_token. Der Kontoinhaber meldet sich bei SingleFax an, prüft die Berechtigungen und gibt den sechsstelligen Code des Agenten ein. Unterstützte Scopes: fax:read, fax:draft, fax:send, inbox:read, credits:read und credits:checkout. Standardberechtigungen: fax:read und credits:read; weitere Scopes ausdrücklich anfordern.

  1. Der Inhaber meldet sich unter https://singlefax.com/dashboard/agent-access an, wählt Agentenname und Berechtigungen und erstellt ausdrücklich einen Enrollment-Token. Dieses nur einmal angezeigte Geheimnis läuft nach zehn Minuten ab und registriert genau einen Agenten. Geben Sie es diesem Agenten. Die API-Bereitstellung nutzt die eigene Browsersitzung des Inhabers unter POST https://singlefax.com/api/auth/agent/identity/manage mit { "action": "enroll", "name": "My agent", "scopes": ["fax:read", "credits:read"] }. Browsercookies werden niemals an den Agenten weitergegeben. Ungenutzte Tokens können dort widerrufen werden.
  2. Registrieren Sie mit POST https://api.singlefax.com/api/auth/agent/identity, Content-Type: application/json und { "type": "service_auth", "enrollment_token": "<owner-issued token>", "login_hint": "<enrolling owner email>" }. Die Antwort enthält registration_id, das geheime claim_token, Ablaufzeit und claim mit user_code, verification_uri und einem Abfrageintervall von fünf Sekunden. Vor Genehmigung wird kein Identitätsnachweis ausgestellt.
  3. Alternativ mit { "type": "anonymous", "enrollment_token": "<owner-issued token>" } registrieren. „Anonym“ bezeichnet hier Zugangsdaten vor Kontozuordnung, keine offene Registrierung. Die Antwort enthält sofort ein signiertes identity_assertion und claim_token. Dessen Austausch liefert nur ein Token ohne Scopes und ohne Kontozugriff. Starten Sie die Genehmigung über POST https://api.singlefax.com/api/auth/agent/identity/claim mit { "claim_token": "<secret>", "email": "<account email>" } und lesen Sie claim_attempt.
  4. Zeigen Sie den Code getrennt an und öffnen Sie verification_uri für den Nutzer. Die URL enthält ein geheimes Zuordnungstoken; fügen Sie den Code nicht in die URL ein. Nur das verifizierte registrierende Konto darf zustimmen. Der Inhaber legt den Namen fest; Scopes dürfen eingeschränkt werden, aber die Freigabe nicht überschreiten. E-Mail-Hinweis und Zuordnungs-E-Mail müssen zum Inhaber passen. Ablehnung ist möglich. Zuordnungen laufen nach zehn Minuten ab; ein neuer Versuch macht den alten Link ungültig. Es wird kein Konto automatisch erstellt.
  5. Fragen Sie POST https://api.singlefax.com/api/auth/oauth2/token mit Content-Type: application/x-www-form-urlencoded und grant_type=urn:workos:agent-auth:grant-type:claim&claim_token=<secret>&resource=https%3A%2F%2Fsinglefax.com%2Fmcp ab. Behandeln Sie authorization_pending, slow_down (Intervall um fünf Sekunden erhöhen), expired_token und access_denied. Die Genehmigung liefert ein nichtssagendes access_token, token_type, expires_in, scope, identity_assertion und assertion_expires. Vorherige Tokens und Nachweise werden ungültig.
  6. Verwenden Sie Authorization: Bearer <access_token> für MCP oder A2A mit den gewährten Scopes. Tokens gelten höchstens eine Stunde. Zum Erneuern denselben Tokenendpunkt mit grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=<identity_assertion>&resource=https%3A%2F%2Fsinglefax.com%2Fmcp nutzen. Es gibt keinen Refresh-Token. Nachweise lassen sich bis zu 30 Tage erneut austauschen, sofern die Registrierung nicht widerrufen ist. EdDSA-Signaturen verwenden /jwks des Ausstellers; typ ist oauth-id-jag+jwt, und iss/aud entsprechen beide dem Aussteller.
  7. Ein Token mit POST https://api.singlefax.com/api/auth/oauth2/revoke und Formularinhalt token=<access_token>&token_type_hint=access_token widerrufen. Dies ist idempotent; der Nachweis bleibt nutzbar. Registrierung mit POST https://api.singlefax.com/api/auth/agent/identity/revoke und JSON { "identity_assertion": "<identity_assertion>" } widerrufen; alle Zugriffstokens und weiteren Austausche werden gesperrt.

Der Kontoinhaber kann Freigaben unter https://singlefax.com/dashboard/agent-access prüfen und widerrufen. Der Widerruf einer Registrierung sperrt alle zugehörigen Zugriffstokens und Nachweiserneuerungen.

Antworten zu Zuordnung und Genehmigung sind privat und niemals zwischenspeicherbar. Halten Sie Zuordnungstokens, Nachweise und Zugriffstokens geheim. Die Tokenausgabe ist pro Inhaber über alle API-Instanzen begrenzt, mit höchstens fünf aktiven ungenutzten Tokens. Nicht freigegebene öffentliche Anfragen verbrauchen kein Registrierungskontingent. Fehlende Tokens liefern enrollment_required; abgelaufene, widerrufene oder verbrauchte invalid_enrollment. Eine fehlgeschlagene Registrierung verbraucht den Enrollment-Token nicht. Bei passiven Bereitschaftsprüfungen keine Registrierungsendpunkte ansprechen.

Dienstermittlung

Ressourcenserver (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

Metadaten geschützter Ressourcen (RFC 9728): Das Stammdokument beschreibt den Ursprung (resource https://singlefax.com); /.well-known/oauth-protected-resource/mcp beschreibt den MCP-Server (resource https://singlefax.com/mcp, auf den WWW-Authenticate zeigt). Beide führen authorization_servers (Aussteller https://api.singlefax.com/api/auth) und scopes_supported auf. Tokens für https://singlefax.com/mcp anfordern.

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

Autorisierungsserver-Metadaten enthalten issuer, authorization_endpoint, token_endpoint, registration_endpoint, jwks_uri, scopes_supported und agent_auth (skill verweist hierher).

API-Ursprung https://api.singlefax.com liefert dieselben Well-known-Dokumente.

Weg A. MCP-OAuth für Chat-Apps

Für Cursor, Claude, ChatGPT, Codex und VS Code verwenden.

  1. MCP https://singlefax.com/mcp hinzufügen (Streamable HTTP).
  2. Bei 401 WWW-Authenticate lesen und obige PRM abrufen.
  3. Dynamische Clientregistrierung: POST {issuer}/oauth2/register (PKCE S256, token_endpoint_auth_method=none für öffentliche Clients).
  4. Authorization Code mit PKCE unter {issuer}/oauth2/authorize.
  5. Token unter {issuer}/oauth2/token.
  6. POST /mcp mit Authorization: Bearer. Für ein übliches Dokument create_upload aufrufen, dem Nutzer uploadPageUrl geben und dann create_fax_draft mit to und uploadToken. base64 ist nur für sehr kleine Dateien. PUT an uploadUrl verwendet das HMAC-Token im Pfad, keinen OAuth-Header. Originale Word-, Excel-, PDF- oder Bilddatei ohne vorherige PDF-Konvertierung senden.

Scopes: openid, profile, email, offline_access, fax:read, fax:draft, fax:send, inbox:read, credits:read, credits:checkout. Für AP2-Guthabenkäufe credits:checkout ausdrücklich anfordern; jede Belastung erfordert weiterhin eine eigene Passkey-Freigabe.

Ohne Authentifizierung akzeptiert POST /mcp nur server/discover. initialize, tools/list und tools/call benötigen OAuth.

Weg A2. A2A (Agent zu Agent)

Agentenkarte: GET https://singlefax.com/.well-known/agent-card.json (A2A 1.0). Endpunkt: POST https://singlefax.com/a2a (JSON-RPC: SendMessage, GetTask, CancelTask; auch die 0.3-Namen message/send, tasks/get, tasks/cancel funktionieren).

  1. OAuth-Server, Scopes und Tokens wie bei Weg A verwenden (Ressource https://singlefax.com/mcp anfordern). Authorization: Bearer senden. An DPoP gebundene Tokens werden auf /a2a nicht akzeptiert.
  2. Einen Datenteil senden: { "skill": "<skill id from the card>", "arguments": { ... } }. Freitext wird nicht interpretiert.
  3. Fax- und Nummern-Skills liefern einen Stripe-Checkout-Link (checkoutUrl). A2A verbraucht niemals Kontoguthaben oder Tarifseiten. Ein zahlungswartender Entwurf hat den Aufgabenstatus input-required. Mit GetTask abfragen.

Für AP2-Guthabenkäufe credits:checkout anfordern und die Händlererweiterung aushandeln. Signierte Warenkorb- und Zahlungsmandate, separate Passkey-Freigabe des Inhabers, Einlösung von Stripe Shared Payment Tokens und buchungsbestätigte Belege sind unter https://singlefax.com/ap2.md dokumentiert.

GetTask mit fax:read verfolgt bei Faxentwürfen die Zustellung und bei Nummernkäufen Zahlung/Bereitstellung. Eine Nummernaufgabe endet mit Aktivierung. Guthabenpaket-Checkout hat keine auftragsbezogene Aufgabe zum Abfragen; prüfen Sie nach Zahlung das Guthaben.

Weg B. API-Schlüssel für Backends und CLI

  1. Schlüssel unter https://singlefax.com/dashboard/api-keys erstellen (sf_live_…).
  2. Prepaid-Guthaben kaufen.
  3. Authorization: Bearer sf_live_… auf https://singlefax.com/api/v1/… oder https://api.singlefax.com/api/v1/….
  4. CLI: npx @singlefax/cli send FILE --to +E164 mit SINGLEFAX_API_KEY. Originale Word-, Excel-, PDF- oder Bilddatei senden, nicht vorher in PDF umwandeln.

Sprachbeispiele (curl, Node, Python, Go, PHP): https://singlefax.com/developers.md

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

Weg C. Delegierte Host-/Agent-JWTs mit Better Auth

Delegierte Fähigkeiten (validate_fax, send_fax, get_fax_status, get_credits, create_credit_checkout) verwenden Gerätefreigabe.

  1. GET https://api.singlefax.com/.well-known/agent-configuration zu Algorithmen, Endpunkten, Modi und Freigabeverfahren lesen. Agent-Auth-Aussteller ist https://api.singlefax.com, abweichend vom auf /api/auth endenden OAuth-Aussteller. Diesen Ursprung als JWT-Audience verwenden. Separate Host- und Agentensignaturschlüssel mit unterstütztem Algorithmus erzeugen und private Schlüssel geheim halten.
  2. Zuerst den Host bereitstellen. Dynamische Hostregistrierung ist deaktiviert. Der Inhaber meldet sich bei SingleFax an und ruft POST https://singlefax.com/api/auth/host/create über seine eigene Browsersitzung auf (API-Entsprechung: https://api.singlefax.com/api/auth/host/create). { "name": "My agent host", "public_key": <host public JWK>, "default_capabilities": [] } übergeben. hostId aus der Antwort kennzeichnet den registrierten Host. Leere Standardwerte erfordern separate Freigaben für Fähigkeiten. Alternativ public_key weglassen, um ein befristetes einmaliges enrollmentToken zu erhalten; der Host ruft anschließend POST https://api.singlefax.com/api/auth/host/enroll mit { "token": <enrollment token>, "public_key": <host public JWK>, "name": "My agent host" } auf. Browsercookies und private Signaturschlüssel niemals an Agenten weitergeben.
  3. Unter POST https://api.singlefax.com/api/auth/agent/register registrieren. Authorization: Bearer <signed host+jwt> und JSON { "name": "My agent", "mode": "delegated", "capabilities": ["validate_fax", "get_fax_status", "get_credits"], "preferred_method": "device_authorization", "force_approval": true } senden. Der JWT-Header verwendet typ: "host+jwt" und ein unterstütztes alg, gegebenenfalls kid des Signatur-JWK. Claims: iss: <registered hostId>, aud: "https://api.singlefax.com", neues jti, aktuelles iat, exp innerhalb von 60 Sekunden und agent_public_key: <agent public JWK>. Mit bereitgestelltem Hostschlüssel signieren. Wiederverwendete JWT-Kennungen werden abgewiesen.
  4. Die Registrierung liefert agent_id, host_id, Status, Fähigkeitsfreigaben und bei Bedarf ein approval-Objekt. Gerätecode anzeigen und verification_uri_complete auf SingleFax öffnen. Der Nutzer meldet sich an und genehmigt unter der zurückgegebenen Prüf-URL. Registrierung, Bereitstellung und Freigabe ändern Kontodaten; passive Scanner dürfen nur Discovery-Dokumente lesen.
  5. GET https://api.singlefax.com/api/auth/agent/status?agent_id=<registered id> mit neuem Host-JWT (iss: <host_id>) abfragen. Nach Genehmigung Agent-JWTs mit dem privaten Agentenschlüssel signieren: Header typ: "agent+jwt", unterstütztes alg/kid; Claims iss: <host_id>, sub: <agent_id>, aud: "https://api.singlefax.com", aktuelles iat, exp innerhalb von 60 Sekunden und neues jti. POST https://api.singlefax.com/api/auth/capability/execute mit Authorization: Bearer <signed agent+jwt> und { "capability": "get_credits", "arguments": {} } oder andere gewährte Fähigkeiten mit dokumentierten Argumenten aufrufen. Dies sind signierte Nachweise, keine API-Schlüssel oder OAuth-Zugriffstokens.
  6. Für einen neuen Gerätecode eines registrierten Agenten POST https://api.singlefax.com/api/auth/agent/device/code mit { "agent_id": "<registered id>" } und signiertem Host-JWT aufrufen. Dieser Endpunkt registriert keinen Agenten. Widerruf über POST https://api.singlefax.com/api/auth/agent/revoke mit { "agent_id": "<registered id>" } und JWT des zugehörigen Hosts oder Inhabersitzung. send_fax erfordert Nutzerverifikation per Passkey und ist nicht autonom.

ID-JAGs oder { "type": "anonymous" } hier nicht per POST senden. Diese Identitätsarten werden nicht unterstützt.

Maschinenzahlungen ohne OAuth

Autonome Zahlung nutzt MPP HTTP 402 unter POST /api/v1/machine/faxes mit Stripe Shared Payment Token oder Tempo USDC. Siehe https://singlefax.com/mpp.md. Cursor erzeugt keine SPTs; nutzen Sie Stripe Link CLI für diese REST-URL, nicht /mcp. Tempo-Wallets zahlen die Tempo-Anforderung unter derselben URL.

HIPAA

Keine PHI über MCP, MPP oder öffentliche API senden. HIPAA-pflichtige Einrichtungen nutzen HIPAA Secure Mode auf der Website mit elektronischem BAA.