singlefax
Dil

SingleFax kimlik doğrulama belgeleri

API anahtarları, MCP için OAuth ve devredilmiş Agent Auth.

Yapay zekâ ajanları ve geliştiriciler için kimlik doğrulama rehberi.

Ajanların SingleFax’ta kimlik doğrulaması. HTML kurulum sayfası: https://singlefax.com/agents

Bu dosya, /.well-known/oauth-authorization-server üzerindeki RFC 8414 üst verisinde belirtilen agent_auth.skill hedefidir.

SingleFax, kullanıcı onayı ve hizmet tarafından imzalanmış kimlik beyanlarıyla Auth.md anonymous ve service_auth kaydını destekler. Anonim kimlik bilgileri, onaydan önce hiçbir hesaba erişemez. Harici sağlayıcı ID-JAG’leri kabul edilmez. Eski Better Auth host/agent JWT akışı C yolunda ayrıca belgelenmiştir.

Auth.md kaydı ve belirteç değişimi

Hedef kitle: mevcut bir SingleFax hesabı adına işlem yapmak için kaydolan yapay zekâ ajanları. Her kayıt yönteminde hesap sahibinin oluşturduğu kayıt izni gereklidir. Geçerli kayıt belirteci olmayan genel istekler, kayıt oluşturulmadan reddedilir. OAuth issuer: https://api.singlefax.com/api/auth; kaynak: https://singlefax.com/mcp. Kayıt işlemi e-posta veya faks göndermez, ödeme almaz.

Desteklenen kayıt yöntemleri: anonymous ve service_auth. Kimlik bilgileri: identity_assertion ve Bearer access_token. Hesap sahibi SingleFax’a giriş yapar, istenen izinleri inceler ve ajanın verdiği altı haneli kodu girer. Desteklenen kapsamlar: fax:read, fax:draft, fax:send, inbox:read, credits:read ve credits:checkout. Varsayılan izinler fax:read ve credits:read; ek kapsamları açıkça isteyin.

  1. Hesap sahibi https://singlefax.com/dashboard/agent-access adresine giriş yapar, ajan adını ve izinleri seçer, açıkça bir kayıt belirteci oluşturur. Bu kısa ömürlü sır yalnızca bir kez gösterilir, on dakika sonra sona erer ve sadece bir ajan kaydedebilir. İlgili ajana verin. API üzerinden hazırlık, POST https://singlefax.com/api/auth/agent/identity/manage adresinde { "action": "enroll", "name": "My agent", "scopes": ["fax:read", "credits:read"] } ile hesap sahibinin birinci taraf tarayıcı oturumunu kullanır. Tarayıcı çerezleri ajanla asla paylaşılmaz. Kullanılmamış belirteçler aynı sayfadan iptal edilebilir.
  2. POST https://api.singlefax.com/api/auth/agent/identity ile Content-Type: application/json ve { "type": "service_auth", "enrollment_token": "<owner-issued token>", "login_hint": "<enrolling owner email>" } kullanarak kaydolun. Yanıtta registration_id, gizli claim_token, sona erme zamanı ve user_code, verification_uri ile beş saniyelik sorgu aralığını içeren claim döner. Onay öncesinde kimlik beyanı verilmez.
  3. Alternatif olarak { "type": "anonymous", "enrollment_token": "<owner-issued token>" } ile kaydolun. Burada anonim sözcüğü herkese açık kayıt değil, sahiplenme öncesi kimlik bilgisini tanımlar. Hemen imzalı identity_assertion ve claim_token döner. Bu ilk beyanı değiştirmek, hiçbir hesaba erişemeyen boş kapsamlı belirteç verir. Onayı POST https://api.singlefax.com/api/auth/agent/identity/claim ile { "claim_token": "<secret>", "email": "<account email>" } kullanarak başlatın; dönen claim_attempt değerini okuyun.
  4. Kodu ayrı gösterin ve kullanıcı için verification_uri açın. URL gizli bir sahiplenme girişimi belirteci içerir; kodu URL’ye eklemeyin. Yalnızca kaydı başlatan doğrulanmış hesap onaylayabilir. Adı hesap sahibi belirler; kapsamlar daraltılabilir ama kayıt iznini aşamaz. E-posta ipucu ve sahiplenme e-postası aynı hesap sahibine ait olmalıdır. Kullanıcı reddedebilir. Sahiplenme on dakika sonra sona erer; yeni girişim eski bağlantıyı geçersiz kılar. Otomatik hesap oluşturulmaz.
  5. POST https://api.singlefax.com/api/auth/oauth2/token adresini Content-Type: application/x-www-form-urlencoded ve grant_type=urn:workos:agent-auth:grant-type:claim&claim_token=<secret>&resource=https%3A%2F%2Fsinglefax.com%2Fmcp ile sorgulayın. authorization_pending, slow_down (aralığı beş saniye artırın), expired_token ve access_denied durumlarını işleyin. Onayla birlikte opak access_token, token_type, expires_in, scope, identity_assertion ve assertion_expires döner. Sahiplenme öncesi belirteç ve beyanlar onayda geçersiz olur.
  6. Verilen kapsamlarla MCP veya A2A üzerinde Authorization: Bearer <access_token> kullanın. Belirteçler en fazla bir saat geçerlidir. Yenilemek için aynı belirteç uç noktasında grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=<identity_assertion>&resource=https%3A%2F%2Fsinglefax.com%2Fmcp kullanın. Yenileme belirteci verilmez. Kayıt iptal edilmedikçe beyanlar 30 güne kadar yeniden değiştirilebilir. EdDSA imzaları issuer’ın /jwks bilgisini kullanır; typ, oauth-id-jag+jwt değeridir; iss/aud ise issuer’a eşittir.
  7. Tek bir belirteci POST https://api.singlefax.com/api/auth/oauth2/revoke ve token=<access_token>&token_type_hint=access_token form gövdesiyle iptal edin. İşlem idempotenttir, beyan kullanılabilir kalır. Kaydı POST https://api.singlefax.com/api/auth/agent/identity/revoke, JSON { "identity_assertion": "<identity_assertion>" } ile iptal edin; tüm erişim belirteçleri ve sonraki değişimler durur.

Hesap sahibi https://singlefax.com/dashboard/agent-access üzerinden izinleri inceleyip iptal edebilir. Kaydın iptali ilişkili tüm erişim belirteçlerini ve beyan yenilemelerini durdurur.

Sahiplenme ve onay yanıtları özeldir, önbelleğe alınamaz. Sahiplenme belirteçlerini, beyanları ve erişim belirteçlerini gizli tutun. Kayıt izni oluşturma, tüm API kopyalarında hesap sahibi başına sınırlıdır; aynı anda en fazla beş kullanılmamış etkin belirteç olabilir. Kayıt izni olmayan genel istekler, hesap sahibinin kayıt kotasını tüketmez. Eksik belirteç enrollment_required; süresi dolmuş, iptal edilmiş veya kullanılmış belirteç invalid_enrollment döndürür. Başarısız kayıt, kayıt belirtecini tüketmez. Pasif hazırlık taramalarında kayıt uç noktalarını denemeyin.

Keşif

Kaynak sunucu (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

Korunan kaynak üst verisi (RFC 9728): kök belge origin’i (resource https://singlefax.com); /.well-known/oauth-protected-resource/mcp, MCP sunucusunu (resource https://singlefax.com/mcp; WWW-Authenticate URL’sinin gösterdiği yer) tanımlar. İkisi de authorization_servers (issuer https://api.singlefax.com/api/auth) ve scopes_supported listeler. Belirteçleri https://singlefax.com/mcp için isteyin.

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

Yetkilendirme sunucusu üst verisi issuer, authorization_endpoint, token_endpoint, registration_endpoint, jwks_uri, scopes_supported ve agent_auth içerir (skill buraya yönlendirir).

API origin’i https://api.singlefax.com aynı well-known belgelerini sunar.

A yolu. MCP OAuth (sohbet uygulamaları)

Cursor, Claude, ChatGPT, Codex ve VS Code için bu yolu kullanın.

  1. MCP https://singlefax.com/mcp ekleyin (Streamable HTTP).
  2. 401 yanıtında WWW-Authenticate okuyup yukarıdaki PRM’yi alın.
  3. Dinamik istemci kaydı: POST {issuer}/oauth2/register (PKCE S256, genel istemciler için token_endpoint_auth_method=none).
  4. {issuer}/oauth2/authorize üzerinde yetkilendirme kodu + PKCE.
  5. Belirteç: {issuer}/oauth2/token.
  6. Authorization: Bearer ile POST /mcp. Tipik belgede create_upload çağırın, kullanıcıya uploadPageUrl verin, sonra to ve uploadToken ile create_fax_draft çağırın. base64 yalnızca çok küçük dosyalar içindir. uploadUrl adresine PUT, yoldaki HMAC belirtecini kullanır; OAuth başlığı gerekmez. Özgün Word, Excel, PDF veya görseli gönderin, önceden PDF’ye dönüştürmeyin.

Kapsamlar: openid, profile, email, offline_access, fax:read, fax:draft, fax:send, inbox:read, credits:read, credits:checkout. AP2 bakiye alımı için credits:checkout kapsamını açıkça isteyin; her tahsilat ayrıca geçiş anahtarı onayı gerektirir.

Kimlik doğrulamasız POST /mcp yalnızca server/discover kabul eder. initialize, tools/list ve tools/call OAuth gerektirir.

A2 yolu. A2A (ajandan ajana)

Ajan kartı: GET https://singlefax.com/.well-known/agent-card.json (A2A 1.0). Uç nokta: POST https://singlefax.com/a2a (JSON-RPC: SendMessage, GetTask, CancelTask; 0.3 adları message/send, tasks/get, tasks/cancel de çalışır).

  1. A yoluyla aynı OAuth sunucusu, kapsamlar ve belirteçleri kullanın (kaynak https://singlefax.com/mcp isteyin). Authorization: Bearer gönderin. /a2a üzerinde DPoP bağlı belirteç kabul edilmez.
  2. Tek veri parçası gönderin: { "skill": "<skill id from the card>", "arguments": { ... } }. Serbest metin yorumlanmaz.
  3. Faks ve numara becerileri Stripe Checkout bağlantısı döndürür (checkoutUrl). A2A hesap bakiyesi veya plan sayfalarını asla harcamaz. Ödeme bekleyen taslak, input-required görev durumundadır. GetTask ile sorgulayın.

AP2 bakiye alımı için credits:checkout isteyip satıcı uzantısını müzakere edin. İmzalı sepet ve ödeme talimatları, hesap sahibinin ayrı geçiş anahtarı onayı, Stripe Shared Payment Token kullanımı ve kayıtlarla doğrulanan belgeler https://singlefax.com/ap2.md adresindedir.

fax:read ile GetTask, faks taslaklarında teslimi, numara ödemelerinde ödeme/etkinleştirmeyi izler. Numara aktif olunca görev tamamlanır. Bakiye paketi ödemesinde siparişe bağlı sorgulanacak görev yoktur; ödeme sonrası bakiyeyi kontrol edin.

B yolu. API anahtarı (sunucu uygulamaları ve CLI)

  1. https://singlefax.com/dashboard/api-keys üzerinden anahtar oluşturun (sf_live_…).
  2. Ön ödemeli bakiye satın alın.
  3. https://singlefax.com/api/v1/… (veya https://api.singlefax.com/api/v1/…) üzerinde Authorization: Bearer sf_live_….
  4. CLI: SINGLEFAX_API_KEY ile npx @singlefax/cli send FILE --to +E164. Özgün Word, Excel, PDF veya görseli iletin; önceden PDF’ye dönüştürmeyin.

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

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

C yolu. Better Auth devredilmiş host/agent JWT’leri

Devredilmiş yetkiler (validate_fax, send_fax, get_fax_status, get_credits, create_credit_checkout) cihaz onayı kullanır.

  1. Algoritmalar, uç noktalar, modlar ve onay yöntemleri için GET https://api.singlefax.com/.well-known/agent-configuration okuyun. Agent Auth issuer değeri https://api.singlefax.com, sonu /api/auth olan OAuth issuer’dan farklıdır. JWT audience olarak bu origin’i kullanın. Desteklenen algoritmayla ayrı host ve ajan imza anahtarları üretin; özel anahtarları gizli tutun.
  2. Önce host’u hazırlayın. Dinamik host kaydı kapalıdır. Hesap sahibi SingleFax’a giriş yapıp kendi birinci taraf tarayıcı oturumuyla POST https://singlefax.com/api/auth/host/create çağırmalıdır (API origin eşdeğeri: https://api.singlefax.com/api/auth/host/create). { "name": "My agent host", "public_key": <host public JWK>, "default_capabilities": [] } sağlayın. Yanıttaki hostId kayıtlı host’u tanımlar. Boş varsayılanlar, yetkiler için ayrı onay gerekmesini sağlar. Alternatif olarak public_key alanını atlayıp süreli, tek kullanımlık enrollmentToken alın; host sonra { "token": <enrollment token>, "public_key": <host public JWK>, "name": "My agent host" } ile POST https://api.singlefax.com/api/auth/host/enroll çağırır. Tarayıcı çerezlerini veya özel imza anahtarlarını ajanla asla paylaşmayın.
  3. POST https://api.singlefax.com/api/auth/agent/register üzerinden kaydolun. Authorization: Bearer <signed host+jwt> ve JSON { "name": "My agent", "mode": "delegated", "capabilities": ["validate_fax", "get_fax_status", "get_credits"], "preferred_method": "device_authorization", "force_approval": true } gönderin. JWT başlığı typ: "host+jwt", desteklenen alg ve varsa imzalayan JWK’nin kid değerini kullanır. İddialar iss: <registered hostId>, aud: "https://api.singlefax.com", yeni jti, güncel iat, 60 saniye içinde exp ve agent_public_key: <agent public JWK> içerir. Hazırlanan host anahtarıyla imzalayın. Tekrar kullanılan JWT kimlikleri reddedilir.
  4. Kayıt yanıtı agent_id, host_id, durum, verilen yetkiler ve gerektiğinde approval nesnesini içerir. Cihaz kodunu gösterip SingleFax sitesindeki verification_uri_complete adresini açın. Kullanıcı dönen doğrulama URL’sinde giriş yapıp onaylar. Kayıt, hazırlama ve onay hesap durumunu değiştirir; pasif tarayıcılar yalnızca keşif belgelerini okumalıdır.
  5. Yeni host JWT’si (iss: <host_id>) ile GET https://api.singlefax.com/api/auth/agent/status?agent_id=<registered id> sorgulayın. Onaydan sonra ajan JWT’lerini özel ajan anahtarıyla imzalayın: başlık typ: "agent+jwt", desteklenen alg/kid; iddialar iss: <host_id>, sub: <agent_id>, aud: "https://api.singlefax.com", güncel iat, 60 saniye içinde exp ve yeni jti. Authorization: Bearer <signed agent+jwt> ve { "capability": "get_credits", "arguments": {} } ile POST https://api.singlefax.com/api/auth/capability/execute çağırın veya verilen başka yetkiyi belgelenmiş argümanlarıyla kullanın. Bunlar imzalı kanıtlardır; API anahtarı veya OAuth erişim belirteci değildir.
  6. Kayıtlı ajana yeni cihaz kodu için { "agent_id": "<registered id>" } ve imzalı host JWT’siyle POST https://api.singlefax.com/api/auth/agent/device/code kullanın. Bu uç nokta ajan kaydedemez. POST https://api.singlefax.com/api/auth/agent/revoke üzerinden { "agent_id": "<registered id>" } ve sahip host JWT’si veya hesap sahibi oturumuyla iptal edin. send_fax, geçiş anahtarıyla kullanıcı doğrulaması gerektirir; otonom değildir.

Buraya ID-JAG veya { "type": "anonymous" } POST göndermeyin. Bu kimlik türleri desteklenmez.

Makine ödemeleri (OAuth değildir)

Otonom ödeme, POST /api/v1/machine/faxes üzerinde Stripe Shared Payment Token veya Tempo USDC ile MPP HTTP 402 kullanır. Bkz. https://singlefax.com/mpp.md. Cursor SPT üretemez; Stripe Link CLI’yi /mcp yerine bu REST URL’sine yönlendirin. Tempo cüzdanları aynı URL’deki Tempo istemini öder.

HIPAA

MCP, MPP veya genel API üzerinden PHI göndermeyin. Kapsam dahilindeki kuruluşlar web sitesinde elektronik BAA ile HIPAA Secure modunu kullanır.