--- title: "Documentazione autenticazione: chiavi API, OAuth e Agent Auth | SingleFax" description: "Autenticazione SingleFax per chiavi API, MCP OAuth e Agent Auth delegato. URL di discovery, permessi, registrazione e uso credenziali." canonical_url: "https://singlefax.com/it/autenticazione" meta: "og:description": "Autenticazione SingleFax per chiavi API, MCP OAuth e Agent Auth delegato. URL di discovery, permessi, registrazione e uso credenziali." "og:image": "https://singlefax.com/images/heroes/og-product.jpg" "og:image:alt": "Documentazione autenticazione: chiavi API, OAuth e Agent Auth" "og:image:height": "630" "og:image:type": image/jpeg "og:image:width": "1200" "og:title": "Documentazione autenticazione: chiavi API, OAuth e Agent Auth | SingleFax" --- > Index of every page on this site: [llms.txt](https://singlefax.com/llms.txt) [singlefax](https://singlefax.com/it) [Invia e ricevi](https://singlefax.com/it/inviare-un-fax) [Per le aziende](https://singlefax.com/it/per-le-aziende)Soluzioni [Prezzi](https://singlefax.com/it/prezzi) [Blog](https://singlefax.com/it/blog)
Lingua EnglishDeutschFrançaisEspañol繁體中文Português do BrasilTürkçe한국어日本語العربية
[Accedi](https://singlefax.com/it/accedi) # Documentazione autenticazione SingleFax Chiavi API, OAuth per MCP e Agent Auth delegato. [Documentazione API](https://singlefax.com/it/sviluppatori) [Server MCP](https://singlefax.com/it/agenti-ia) [Riferimento OpenAPI](https://singlefax.com/it/openapi) [Markdown](https://singlefax.com/auth.md) Guida all’autenticazione per agenti AI e sviluppatori. Come gli agenti si autenticano su SingleFax. Installazione HTML: https://singlefax.com/agents Questo file è la destinazione `agent_auth.skill` indicata nei metadati RFC 8414 su `/.well-known/oauth-authorization-server`. SingleFax supporta registrazione Auth.md `anonymous` e `service_auth`, con approvazione utente e attestazioni d’identità firmate dal servizio. Le credenziali anonime non accedono ad account prima dell’approvazione. Gli ID-JAG di fornitori esterni non sono accettati. Il precedente flusso JWT host/agente Better Auth è nel Percorso C. ## Registrazione Auth.md e scambio token Destinatari: agenti AI che si registrano per un account SingleFax esistente. **Ogni metodo richiede un’autorizzazione di registrazione emessa dal titolare.** Richieste pubbliche senza token valido sono respinte prima di creare la registrazione. Issuer OAuth: `https://api.singlefax.com/api/auth`; risorsa: `https://singlefax.com/mcp`. Registrarsi non invia email o fax e non addebita pagamenti. Metodi: `anonymous` e `service_auth`. Credenziali: `identity_assertion` e Bearer `access_token`. Il titolare accede, verifica i permessi e inserisce il codice a sei cifre dell’agente. Scope supportati: `fax:read`, `fax:draft`, `fax:send`, `inbox:read`, `credits:read`, `credits:checkout`. Predefiniti: `fax:read` e `credits:read`; richiedi esplicitamente gli altri. 1. Il titolare accede a https://singlefax.com/dashboard/agent-access, sceglie nome e permessi e crea esplicitamente un token di registrazione. Il segreto è mostrato una volta, scade in dieci minuti e registra un solo agente. Consegnalo a quell’agente. Il provisioning API usa la sessione browser proprietaria su `POST https://singlefax.com/api/auth/agent/identity/manage` con `{ "action": "enroll", "name": "My agent", "scopes": ["fax:read", "credits:read"] }`. I cookie non vengono mai condivisi con l’agente. I token inutilizzati sono revocabili dalla stessa pagina. 2. Registrati con `POST https://api.singlefax.com/api/auth/agent/identity`, `Content-Type: application/json` e `{ "type": "service_auth", "enrollment_token": "", "login_hint": "" }`. Ricevi `registration_id`, il segreto `claim_token`, scadenza e `claim` con `user_code`, `verification_uri` e intervallo di polling di cinque secondi. Nessuna attestazione prima dell’approvazione. 3. In alternativa usa `{ "type": "anonymous", "enrollment_token": "" }`. Anonimo descrive la credenziale prima dell’associazione, non una registrazione pubblica aperta. Ricevi subito `identity_assertion` firmato e `claim_token`. Scambiando l’attestazione preliminare ottieni un token senza scope, incapace di accedere ad account. Avvia l’approvazione con `POST https://api.singlefax.com/api/auth/agent/identity/claim` e `{ "claim_token": "", "email": "" }`; leggi `claim_attempt` restituito. 4. Mostra il codice separatamente e apri `verification_uri` per l’utente. L’URL contiene un token segreto di associazione: non aggiungere il codice all’URL. Solo l’account verificato che ha avviato la registrazione può approvare. Nome fissato dal titolare; scope riducibili, mai oltre i permessi iniziali. Email suggerita e di associazione devono coincidere con il titolare. L’utente può rifiutare. Scadenza dieci minuti; un nuovo tentativo invalida il vecchio link. Nessun account creato automaticamente. 5. Interroga `POST https://api.singlefax.com/api/auth/oauth2/token` con `Content-Type: application/x-www-form-urlencoded` e `grant_type=urn:workos:agent-auth:grant-type:claim&claim_token=&resource=https%3A%2F%2Fsinglefax.com%2Fmcp`. Gestisci `authorization_pending`, `slow_down` (aumenta l’intervallo di cinque secondi), `expired_token`, `access_denied`. L’approvazione restituisce `access_token` opaco, `token_type`, `expires_in`, `scope`, `identity_assertion`, `assertion_expires`. Token e attestazioni preliminari vengono invalidati. 6. Usa `Authorization: Bearer ` su MCP o A2A con gli scope concessi. I token durano al massimo un’ora. Per rinnovare usa lo stesso endpoint con `grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=&resource=https%3A%2F%2Fsinglefax.com%2Fmcp`; non viene emesso refresh token. Le attestazioni sono riscambiabili fino a 30 giorni salvo revoca. Le firme EdDSA usano `/jwks` dell’issuer; `typ` è `oauth-id-jag+jwt`, e `iss`/ `aud` coincidono con l’issuer. 7. Revoca un token con `POST https://api.singlefax.com/api/auth/oauth2/revoke`, corpo form `token=&token_type_hint=access_token`. È idempotente e lascia utilizzabile l’attestazione. Revoca la registrazione con `POST https://api.singlefax.com/api/auth/agent/identity/revoke`, JSON `{ "identity_assertion": "" }`: cessano tutti i token e scambi successivi. Il titolare può verificare e revocare i permessi su https://singlefax.com/dashboard/agent-access. Revocare la registrazione blocca tutti i token collegati e rinnovi delle attestazioni. Le risposte di associazione e approvazione sono private e mai memorizzabili in cache. Proteggi token, attestazioni e access token. L’emissione è limitata per titolare tra tutte le repliche API, con massimo cinque token attivi inutilizzati. Le richieste pubbliche senza autorizzazione non consumano la quota del titolare. Token mancanti restituiscono `enrollment_required`; scaduti, revocati o consumati `invalid_enrollment`. Una registrazione fallita non consuma il token. Non sondare endpoint di registrazione nelle scansioni passive. ## Discovery Server risorse (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 ``` Metadati risorsa protetta (RFC 9728): il documento radice descrive l’origine (`resource` `https://singlefax.com`); `/.well-known/oauth-protected-resource/mcp` descrive MCP (`resource` `https://singlefax.com/mcp`, destinazione dell’URL `WWW-Authenticate`). Entrambi elencano `authorization_servers` (issuer `https://api.singlefax.com/api/auth`) e `scopes_supported`. Richiedi token per `https://singlefax.com/mcp`. ``` GET https://singlefax.com/.well-known/oauth-authorization-server GET https://singlefax.com/.well-known/oauth-authorization-server/api/auth ``` I metadati del server autorizzativo includono `issuer`, `authorization_endpoint`, `token_endpoint`, `registration_endpoint`, `jwks_uri`, `scopes_supported`, `agent_auth` (`skill` rimanda qui). L’origine API `https://api.singlefax.com` espone gli stessi documenti well-known. ## Percorso A. MCP OAuth (chat) Usalo per Cursor, Claude, ChatGPT, Codex e VS Code. 1. Aggiungi MCP `https://singlefax.com/mcp` (Streamable HTTP). 2. Su 401 leggi `WWW-Authenticate` e recupera PRM sopra. 3. Registrazione client dinamica: `POST {issuer}/oauth2/register` (PKCE S256, `token_endpoint_auth_method=none` per client pubblici). 4. Codice autorizzativo + PKCE su `{issuer}/oauth2/authorize`. 5. Token su `{issuer}/oauth2/token`. 6. `POST /mcp` con `Authorization: Bearer`. Per documenti normali chiama `create_upload`, dai all’utente `uploadPageUrl`, poi `create_fax_draft` con `to` e `uploadToken`. `base64` solo per file minimi. PUT a `uploadUrl` usa il token HMAC nel percorso, senza header OAuth. Invia Word, Excel, PDF o immagine originali, senza conversione preventiva. Scope: `openid`, `profile`, `email`, `offline_access`, `fax:read`, `fax:draft`, `fax:send`, `inbox:read`, `credits:read`, `credits:checkout`. Richiedi `credits:checkout` per acquisti crediti AP2; ogni addebito richiede comunque approvazione passkey separata. Senza autenticazione `POST /mcp` accetta solo `server/discover`. `initialize`, `tools/list`, `tools/call` richiedono OAuth. ## Percorso A2. A2A (agente-agente) Scheda agente: `GET https://singlefax.com/.well-known/agent-card.json` (A2A 1.0). Endpoint: `POST https://singlefax.com/a2a` (JSON-RPC: `SendMessage`, `GetTask`, `CancelTask`; funzionano anche i nomi 0.3 `message/send`, `tasks/get`, `tasks/cancel`). 1. Usa server OAuth, scope e token del Percorso A (risorsa `https://singlefax.com/mcp`). Invia `Authorization: Bearer`. Token vincolati DPoP non accettati su `/a2a`. 2. Invia una sola parte dati: `{ "skill": "", "arguments": { ... } }`. Il testo libero non viene interpretato. 3. Le funzioni fax e numeri restituiscono link Stripe Checkout ( `checkoutUrl`). A2A non spende crediti o pagine del piano. Una bozza in attesa di pagamento ha stato `input-required`. Interroga con `GetTask`. Per crediti AP2 richiedi `credits:checkout` e negozia l’estensione merchant. Mandati firmati di carrello e pagamento, approvazione passkey separata, utilizzo SPT e ricevute confermate nel registro: https://singlefax.com/ap2.md. `GetTask` con `fax:read` segue la consegna per bozze fax e pagamento/provisioning per numeri. Il compito numero termina all’attivazione. I crediti non hanno task collegato a un ordine: verifica il saldo dopo il pagamento. ## Percorso B. Chiave API (backend e CLI) 1. Crea una chiave su https://singlefax.com/dashboard/api-keys ( `sf_live_…`). 2. Acquista crediti prepagati. 3. `Authorization: Bearer sf_live_…` su `https://singlefax.com/api/v1/…` (o `https://api.singlefax.com/api/v1/…`). 4. CLI: `npx @singlefax/cli send FILE --to +E164` con `SINGLEFAX_API_KEY`. Passa Word, Excel, PDF o immagine originali, senza conversione preventiva. Esempi di linguaggio (curl, Node, Python, Go, PHP): https://singlefax.com/developers.md OpenAPI: https://singlefax.com/openapi.json ## Percorso C. JWT host/agente delegati Better Auth Le capacità delegate (`validate_fax`, `send_fax`, `get_fax_status`, `get_credits`, `create_credit_checkout`) usano approvazione dispositivo. 1. Leggi `GET https://api.singlefax.com/.well-known/agent-configuration` per algoritmi, endpoint, modalità e approvazioni. **L’issuer Agent Auth è `https://api.singlefax.com`**, distinto dall’issuer OAuth che termina in `/api/auth`. Usa questa origine come audience JWT. Genera chiavi separate host e agente con algoritmo supportato; conserva le private al sicuro. 2. **Prepara prima l’host.** Registrazione dinamica host disabilitata. Il titolare deve accedere a SingleFax e chiamare `POST https://singlefax.com/api/auth/host/create` (equivalente API: https://api.singlefax.com/api/auth/host/create) dalla sessione browser proprietaria. Fornisci `{ "name": "My agent host", "public_key": , "default_capabilities": [] }`; `hostId` nella risposta identifica l’host. Impostazioni iniziali vuote assicurano approvazione separata delle capacità. Oppure ometti `public_key` per ricevere `enrollmentToken` monouso a scadenza; l’host chiama `POST https://api.singlefax.com/api/auth/host/enroll` con `{ "token": , "public_key": , "name": "My agent host" }`. Mai condividere cookie o chiavi private con l’agente. 3. Registrati su `POST https://api.singlefax.com/api/auth/agent/register`. Invia `Authorization: Bearer ` e JSON `{ "name": "My agent", "mode": "delegated", "capabilities": ["validate_fax", "get_fax_status", "get_credits"], "preferred_method": "device_authorization", "force_approval": true }`. Header JWT: `typ: "host+jwt"`, `alg` supportato e `kid` del JWK firmatario se presente. Claim: `iss: `, `aud: "https://api.singlefax.com"`, `jti` nuovo, `iat` corrente, `exp` entro 60 secondi e `agent_public_key: `. Firma con la chiave host predisposta. Identificatori JWT riusati vengono respinti. 4. La registrazione restituisce `agent_id`, `host_id`, stato, capacità e oggetto `approval` quando necessario. Mostra il codice dispositivo e apri `verification_uri_complete` su SingleFax. L’utente accede e approva all’URL restituito. Registrazione, provisioning e approvazione cambiano l’account; scanner passivi devono solo leggere discovery. 5. Interroga `GET https://api.singlefax.com/api/auth/agent/status?agent_id=` con JWT host nuovo ( `iss: `). Dopo l’approvazione firma JWT agente con la sua chiave privata: header `typ: "agent+jwt"`, `alg`/ `kid` supportati; claim `iss: `, `sub: `, `aud: "https://api.singlefax.com"`, `iat` corrente, `exp` entro 60 secondi e `jti` nuovo. Chiama `POST https://api.singlefax.com/api/auth/capability/execute` con `Authorization: Bearer ` e `{ "capability": "get_credits", "arguments": {} }`, o un’altra capacità concessa con gli argomenti documentati. Sono prove firmate, non chiavi API o access token OAuth. 6. Per un nuovo codice dispositivo di un agente registrato, `POST https://api.singlefax.com/api/auth/agent/device/code` con `{ "agent_id": "" }` e JWT host firmato. Questo endpoint non registra agenti. Revoca tramite `POST https://api.singlefax.com/api/auth/agent/revoke` con `{ "agent_id": "" }` e JWT host proprietario o sessione titolare. `send_fax` richiede verifica utente con passkey; non è autonomo. **Non** inviare ID-JAG o `{ "type": "anonymous" }` via POST qui: tipi d’identità non supportati. ## Pagamenti macchina (non OAuth) Pagamento autonomo: MPP HTTP 402 su `POST /api/v1/machine/faxes` con Stripe Shared Payment Token o Tempo USDC. Vedi https://singlefax.com/mpp.md. Cursor non genera SPT: usa Stripe Link CLI su quell’URL REST, non `/mcp`. I wallet Tempo pagano la richiesta Tempo sullo stesso URL. ## HIPAA Non inviare PHI su MCP, MPP o API pubblica. Gli enti soggetti usano HIPAA Secure sul sito con BAA elettronico. [singlefax](https://singlefax.com/it) Invia una volta. Ricevi quando serve. [![Scarica su Google Play](https://singlefax.com/images/google-play-badge.png)](https://play.google.com/store/apps/details?id=com.monocube.singlefax) [Aggiungi a Chrome](https://chromewebstore.google.com/detail/singlefax-fax-a-document/ojpmpilgkmjcfebhpkdmmjlkbcifkkej) [SingleFax su LinkedIn](https://www.linkedin.com/company/singlefax/) [SingleFax su Facebook](https://www.facebook.com/singlefax) [SingleFax su Instagram](https://www.instagram.com/singlefax.app) [SingleFax su Threads](https://www.threads.com/@singlefax.app) [SingleFax su YouTube](https://www.youtube.com/@singlefax) [SingleFax su GitHub](https://github.com/SingleFax) ## Servizi fax - [Invia un fax](https://singlefax.com/it/inviare-un-fax?type=send) - [Ricevi fax](https://singlefax.com/it/inviare-un-fax?type=receive) - [Numero gratuito per 24 ore](https://singlefax.com/it/numero-fax-gratuito) - [Numero permanente](https://singlefax.com/it/numero-fax-permanente) - [Portabilità del numero](https://singlefax.com/it/portabilita-numero) - [Test fax](https://singlefax.com/it/numero-test-fax) - [Piani aziendali](https://singlefax.com/it/per-le-aziende) - [HIPAA Secure](https://singlefax.com/it/fax-hipaa) - [Fax online](https://singlefax.com/it/inviare-fax-online) - [Fax via email](https://singlefax.com/it/fax-via-email) - [Fax via WhatsApp](https://singlefax.com/it/fax-via-whatsapp) ## Invii all'IRS - [Tutti gli invii IRS](https://singlefax.com/it/invii-irs) - [EIN · Modulo SS-4](https://singlefax.com/it/richiedere-ein) - [Modulo 5472](https://singlefax.com/it/inviare-modulo-5472) - [Modulo 7004](https://singlefax.com/it/inviare-modulo-7004) - [Modulo 2553](https://singlefax.com/it/inviare-modulo-2553) - [Modulo 2848](https://singlefax.com/it/inviare-modulo-2848) - [Modulo 4506-T](https://singlefax.com/it/inviare-modulo-4506-t) - [Modulo 8821](https://singlefax.com/it/inviare-modulo-8821) - [Modulo 8802](https://singlefax.com/it/inviare-modulo-8802) - [Modulo 8655](https://singlefax.com/it/inviare-modulo-8655) - [Modulo 3911](https://singlefax.com/it/inviare-modulo-3911) - [Modulo 8233](https://singlefax.com/it/inviare-modulo-8233) - [NY POA-1](https://singlefax.com/it/inviare-modulo-ny-poa-1) ## Strumenti e risorse - [Strumenti fax gratuiti](https://singlefax.com/it/strumenti-fax-gratuiti) - [Prepara un PDF per fax](https://singlefax.com/it/preparare-fax) - [Pagina di prova stampabile](https://singlefax.com/it/pagina-prova-fax) - [Copertine fax](https://singlefax.com/it/copertina-fax) - [App mobile](https://singlefax.com/it/app-mobile) - [Estensione Chrome](https://singlefax.com/it/estensione-chrome) - [Sviluppatori](https://singlefax.com/it/sviluppatori) - [Agenti fax IA](https://singlefax.com/it/agenti-ia) - [Gestione delle versioni](https://singlefax.com/it/gestione-versioni) - [Numeri fax della Camera USA](https://singlefax.com/it/numeri-fax/camera-usa) - [Numeri fax del Senato USA](https://singlefax.com/it/numeri-fax/senato-usa) - [Numeri fax dei governatori USA](https://singlefax.com/it/numeri-fax/governatori-usa) ## SingleFax - [Prezzi](https://singlefax.com/it/prezzi) - [Blog](https://singlefax.com/it/blog) - [Chi siamo](https://singlefax.com/it/chi-siamo) - [Contatti](https://singlefax.com/it/contatti) - [Assistenza](https://singlefax.com/it/assistenza) © 2026 SingleFax [Privacy](https://singlefax.com/it/informativa-privacy) [Condizioni](https://singlefax.com/it/condizioni-servizio) [Rimborsi](https://singlefax.com/it/politica-rimborsi) [Segnala un abuso](https://singlefax.com/it/segnala-abuso) ```json {"@context":"https://schema.org","@graph":[{"@id":"https://singlefax.com/it#website","@type":"WebSite","description":"Con SingleFax puoi inviare e ricevere fax quando ti servono, dal telefono o dal computer. Non occorre registrarsi né creare un account.","inLanguage":"it","name":"SingleFax – Invia e ricevi fax senza abbonamento","url":"https://singlefax.com/it","translationOfWork":{"@id":"https://singlefax.com/#website"}},{"@id":"https://singlefax.com/it/autenticazione#webpage","@type":"WebPage","description":"Autenticazione SingleFax per chiavi API, MCP OAuth e Agent Auth delegato. URL di discovery, permessi, registrazione e uso credenziali.","name":"Documentazione autenticazione: chiavi API, OAuth e Agent Auth","url":"https://singlefax.com/it/autenticazione","isPartOf":{"@id":"https://singlefax.com/it#website"},"potentialAction":[{"@type":"ReadAction","target":["https://singlefax.com/it/autenticazione"]}]}]} ```