--- title: "Autenticação: chaves de API, OAuth e Agent Auth | SingleFax" description: "Autenticação SingleFax com chaves de API, MCP OAuth e Agent Auth delegado. URLs de descoberta, permissões, registro e uso de credenciais." canonical_url: "https://singlefax.com/pt-br/autenticacao" meta: "og:description": "Autenticação SingleFax com chaves de API, MCP OAuth e Agent Auth delegado. URLs de descoberta, permissões, registro e uso de credenciais." "og:image": "https://singlefax.com/images/heroes/og-product.jpg" "og:image:alt": "Autenticação: chaves de API, OAuth e Agent Auth" "og:image:height": "630" "og:image:type": image/jpeg "og:image:width": "1200" "og:title": "Autenticação: chaves de API, OAuth e Agent Auth | SingleFax" --- > Index of every page on this site: [llms.txt](https://singlefax.com/llms.txt) [singlefax](https://singlefax.com/pt-br) [Enviar e receber](https://singlefax.com/pt-br/enviar-fax) [Para empresas](https://singlefax.com/pt-br/para-empresas)Soluções [Preços](https://singlefax.com/pt-br/precos) [Blog](https://singlefax.com/pt-br/blog)
Idioma EnglishDeutschFrançaisEspañolItaliano繁體中文Türkçe한국어日本語العربية
[Entrar](https://singlefax.com/pt-br/entrar) # Documentação de autenticação SingleFax Chaves de API, OAuth para MCP e Agent Auth delegado. [Documentação API](https://singlefax.com/pt-br/desenvolvedores) [Servidor MCP](https://singlefax.com/pt-br/agentes-ia) [Referência OpenAPI](https://singlefax.com/pt-br/openapi) [Markdown](https://singlefax.com/auth.md) Guia de autenticação para agentes de IA e desenvolvedores. Como os agentes se autenticam no SingleFax. Instalação HTML: https://singlefax.com/agents Este arquivo é o destino `agent_auth.skill` anunciado nos metadados RFC 8414 em `/.well-known/oauth-authorization-server`. O SingleFax aceita registro Auth.md `anonymous` e `service_auth`, com aprovação do usuário e asserções de identidade assinadas pelo serviço. Credenciais anônimas não têm acesso a contas antes da aprovação. ID-JAGs de provedores externos não são aceitos. O fluxo anterior de JWT de host/agente do Better Auth está documentado separadamente no Caminho C. ## Registro Auth.md e troca de tokens Público: agentes de IA que se registram para agir em nome de uma conta SingleFax existente. **Todos os métodos de registro exigem uma inscrição emitida pelo proprietário.** Solicitações públicas sem um token de inscrição válido são rejeitadas antes da criação de um registro. O emissor OAuth é `https://api.singlefax.com/api/auth`; o recurso é `https://singlefax.com/mcp`. O registro nunca envia e-mails ou faxes nem realiza cobranças. Métodos de registro aceitos: `anonymous` e `service_auth`. Credenciais: `identity_assertion` e Bearer `access_token`. O proprietário da conta entra no SingleFax, revisa as permissões solicitadas e informa o código de seis dígitos do agente. Os escopos aceitos são `fax:read`, `fax:draft`, `fax:send`, `inbox:read`, `credits:read` e `credits:checkout`. As permissões padrão são `fax:read` e `credits:read`; solicite escopos adicionais explicitamente. 1. O proprietário entra em https://singlefax.com/dashboard/agent-access, escolhe o nome do agente e as permissões permitidas e cria explicitamente um token de inscrição. Esse segredo temporário é exibido uma única vez, expira após dez minutos e só pode registrar um agente. Entregue-o a esse agente. O provisionamento pela API usa a sessão própria do proprietário no navegador em `POST https://singlefax.com/api/auth/agent/identity/manage` com `{ "action": "enroll", "name": "My agent", "scopes": ["fax:read", "credits:read"] }`. Os cookies do navegador nunca são compartilhados com o agente. O proprietário pode revogar tokens não utilizados na mesma página. 2. Registre usando `POST https://api.singlefax.com/api/auth/agent/identity` com `Content-Type: application/json` e `{ "type": "service_auth", "enrollment_token": "", "login_hint": "" }`. Isso retorna `registration_id`, um segredo `claim_token`, a expiração e `claim` com `user_code`, `verification_uri` e intervalo de consulta de cinco segundos. Nenhuma asserção é emitida antes da aprovação. 3. Como alternativa, registre com `{ "type": "anonymous", "enrollment_token": "" }`. Aqui, anônimo descreve a credencial anterior à vinculação, e não um cadastro público aberto. Isso retorna imediatamente um `identity_assertion` assinado e um `claim_token`. Trocar essa asserção anterior à vinculação gera um token sem escopos, que não pode acessar nenhuma conta. Inicie sua aprovação usando `POST https://api.singlefax.com/api/auth/agent/identity/claim` com `{ "claim_token": "", "email": "" }`; leia o `claim_attempt` retornado. 4. Mostre o código separadamente e abra `verification_uri` para o usuário. A URL contém um token secreto da tentativa de vinculação; não inclua o código nessa URL. Somente a conta verificada que emitiu a inscrição pode aprovar. O nome é definido pelo proprietário; os escopos solicitados podem ser reduzidos, mas não podem exceder as permissões da inscrição. A indicação de e-mail e o e-mail de vinculação devem corresponder ao proprietário que emitiu a inscrição. O usuário pode recusar. As tentativas de vinculação expiram após dez minutos; uma nova tentativa invalida o link anterior. Nenhuma conta é criada automaticamente. 5. Consulte `POST https://api.singlefax.com/api/auth/oauth2/token` com `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`. Trate `authorization_pending`, `slow_down` (aumente o intervalo em cinco segundos), `expired_token` e `access_denied`. A aprovação retorna um `access_token` opaco, `token_type`, `expires_in`, `scope`, `identity_assertion` e `assertion_expires`. Tokens e asserções anteriores à vinculação são invalidados na aprovação. 6. Use `Authorization: Bearer ` no MCP ou A2A com os escopos concedidos. Os tokens duram no máximo uma hora. Para renovar, use o mesmo endpoint de tokens com `grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=&resource=https%3A%2F%2Fsinglefax.com%2Fmcp`. Não é emitido um token de atualização. As asserções podem ser trocadas novamente por até 30 dias, a menos que o registro seja revogado. Suas assinaturas EdDSA usam o `/jwks` do emissor; `typ` é `oauth-id-jag+jwt`, e `iss`/ `aud` são ambos iguais ao emissor. 7. Revogue um token com `POST https://api.singlefax.com/api/auth/oauth2/revoke`, corpo de formulário `token=&token_type_hint=access_token`. A operação é idempotente e mantém a asserção utilizável. Revogue o registro com `POST https://api.singlefax.com/api/auth/agent/identity/revoke`, JSON `{ "identity_assertion": "" }`; todos os tokens de acesso e as trocas posteriores são interrompidos. O proprietário da conta pode revisar e revogar concessões em https://singlefax.com/dashboard/agent-access. Revogar um registro interrompe todos os tokens de acesso associados e a renovação por asserções. As respostas de vinculação e aprovação são privadas e nunca podem ser armazenadas em cache. Mantenha em segredo os tokens de vinculação, as asserções e os tokens de acesso. A emissão de inscrições é limitada por proprietário entre todas as réplicas da API, com no máximo cinco tokens ativos não utilizados. Solicitações públicas sem inscrição não consomem a cota de registros do proprietário. Tokens ausentes retornam `enrollment_required`; tokens expirados, revogados ou consumidos retornam `invalid_enrollment`. Um registro malsucedido não consome o token de inscrição. Não sonde endpoints de registro durante verificações passivas de prontidão. ## Descoberta Servidor de recursos (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 ``` Metadados do recurso protegido (RFC 9728): o documento raiz descreve a origem (`resource` `https://singlefax.com`); `/.well-known/oauth-protected-resource/mcp` descreve o servidor MCP (`resource` `https://singlefax.com/mcp`, para o qual aponta a URL `WWW-Authenticate`). Ambos listam `authorization_servers` (emissor `https://api.singlefax.com/api/auth`) e `scopes_supported`. Solicite tokens para `https://singlefax.com/mcp`. ``` GET https://singlefax.com/.well-known/oauth-authorization-server GET https://singlefax.com/.well-known/oauth-authorization-server/api/auth ``` Os metadados do servidor de autorização incluem `issuer`, `authorization_endpoint`, `token_endpoint`, `registration_endpoint`, `jwks_uri`, `scopes_supported` e `agent_auth` (`skill` aponta para cá). A origem da API `https://api.singlefax.com` disponibiliza os mesmos documentos well-known. ## Caminho A. MCP OAuth (aplicativos de chat) Use esta opção para Cursor, Claude, ChatGPT, Codex e VS Code. 1. Adicione MCP `https://singlefax.com/mcp` (Streamable HTTP). 2. Ao receber 401, leia `WWW-Authenticate` e obtenha os PRM acima. 3. Registro dinâmico de clientes: `POST {issuer}/oauth2/register` (PKCE S256, `token_endpoint_auth_method=none` para clientes públicos). 4. Código de autorização + PKCE em `{issuer}/oauth2/authorize`. 5. Token em `{issuer}/oauth2/token`. 6. `POST /mcp` com `Authorization: Bearer`. Para um documento comum, chame `create_upload`, forneça `uploadPageUrl` ao usuário e depois `create_fax_draft` com `to` e `uploadToken`. `base64` serve apenas para arquivos muito pequenos. PUT para `uploadUrl` usa o token HMAC no caminho, sem cabeçalho OAuth. Envie o Word, Excel, PDF ou imagem original; não converta para PDF antes. Escopos: `openid`, `profile`, `email`, `offline_access`, `fax:read`, `fax:draft`, `fax:send`, `inbox:read`, `credits:read`, `credits:checkout`. Solicite `credits:checkout` explicitamente para compras de créditos pré-pagos por AP2; cada cobrança ainda exige uma aprovação separada com chave de acesso. Sem autenticação, `POST /mcp` aceita apenas `server/discover`. `initialize`, `tools/list` e `tools/call` exigem OAuth. ## Caminho A2. A2A (agente para agente) Cartão do agente: `GET https://singlefax.com/.well-known/agent-card.json` (A2A 1.0). Endpoint: `POST https://singlefax.com/a2a` (JSON-RPC: `SendMessage`, `GetTask`, `CancelTask`; os nomes da versão 0.3 `message/send`, `tasks/get`, `tasks/cancel` também funcionam). 1. Use o mesmo servidor OAuth, escopos e tokens do Caminho A (solicite o recurso `https://singlefax.com/mcp`). Envie `Authorization: Bearer`. Tokens vinculados a DPoP não são aceitos em `/a2a`. 2. Envie uma única parte de dados: `{ "skill": "", "arguments": { ... } }`. Texto livre não é interpretado. 3. As habilidades de fax e números retornam um link do Stripe Checkout ( `checkoutUrl`). O A2A nunca gasta créditos pré-pagos da conta nem páginas do plano. Um rascunho aguardando pagamento tem o estado de tarefa `input-required`. Consulte com `GetTask`. Para comprar créditos pré-pagos por AP2, solicite `credits:checkout` e negocie a extensão do comerciante. Os mandatos assinados de carrinho e pagamento, a aprovação separada do proprietário com chave de acesso, o resgate de Stripe Shared Payment Token e os recibos confirmados no livro de movimentações estão documentados em https://singlefax.com/ap2.md. `GetTask` com `fax:read` acompanha a entrega de fax para rascunhos de fax e o pagamento/provisionamento para compras de números. Uma tarefa de número termina quando o número fica ativo. A compra de um pacote de créditos pré-pagos não tem tarefa vinculada a pedido para consultar; confira o saldo após o pagamento. ## Caminho B. Chave de API (backends e CLI) 1. Crie uma chave em https://singlefax.com/dashboard/api-keys ( `sf_live_…`). 2. Compre créditos pré-pagos. 3. `Authorization: Bearer sf_live_…` em `https://singlefax.com/api/v1/…` (ou `https://api.singlefax.com/api/v1/…`). 4. CLI: `npx @singlefax/cli send FILE --to +E164` com `SINGLEFAX_API_KEY`. Use o Word, Excel, PDF ou imagem original; não converta para PDF antes. Exemplos por linguagem (curl, Node, Python, Go, PHP): https://singlefax.com/developers.md OpenAPI: https://singlefax.com/openapi.json ## Caminho C. JWTs delegados de host/agente do Better Auth As capacidades delegadas (`validate_fax`, `send_fax`, `get_fax_status`, `get_credits`, `create_credit_checkout`) usam aprovação de dispositivo. 1. Leia `GET https://api.singlefax.com/.well-known/agent-configuration` para ver os algoritmos, endpoints, modos e métodos de aprovação. Seu **emissor do Agent Auth é `https://api.singlefax.com`**, diferente do emissor OAuth terminado em `/api/auth`. Use essa origem como audiência do JWT. Gere chaves de assinatura separadas para host e agente usando um algoritmo aceito; mantenha as chaves privadas em segredo. 2. **Provisione o host primeiro.** O registro dinâmico de hosts está desativado. O proprietário da conta deve entrar no SingleFax e chamar `POST https://singlefax.com/api/auth/host/create` (equivalente na origem da API: https://api.singlefax.com/api/auth/host/create) usando sua sessão própria do navegador. Forneça `{ "name": "My agent host", "public_key": , "default_capabilities": [] }`. O `hostId` da resposta identifica o host registrado. Os padrões vazios garantem que as capacidades exijam aprovação separada. Como alternativa, omita `public_key` para receber um `enrollmentToken` de uso único com expiração; o host então chama `POST https://api.singlefax.com/api/auth/host/enroll` com `{ "token": , "public_key": , "name": "My agent host" }`. Nunca compartilhe cookies do navegador nem chaves privadas de assinatura com um agente. 3. Registre em `POST https://api.singlefax.com/api/auth/agent/register`. Envie `Authorization: Bearer ` e JSON `{ "name": "My agent", "mode": "delegated", "capabilities": ["validate_fax", "get_fax_status", "get_credits"], "preferred_method": "device_authorization", "force_approval": true }`. O cabeçalho JWT usa `typ: "host+jwt"` e um `alg` aceito (e o `kid` da JWK de assinatura, se houver). As declarações incluem `iss: `, `aud: "https://api.singlefax.com"`, um `jti` novo, `iat` atual, `exp` dentro de 60 segundos e `agent_public_key: `. Assine com a chave do host provisionado. Identificadores JWT reutilizados são rejeitados. 4. O registro retorna `agent_id`, `host_id`, status, concessões de capacidades e um objeto `approval` quando necessário. Mostre seu código de dispositivo e abra seu `verification_uri_complete` no site do SingleFax. O usuário entra e aprova na URL de verificação retornada. Registro, provisionamento e aprovação alteram o estado da conta; scanners passivos devem ler apenas documentos de descoberta. 5. Consulte `GET https://api.singlefax.com/api/auth/agent/status?agent_id=` usando um JWT de host novo ( `iss: `). Após a aprovação, assine JWTs de agente com a chave privada do agente: cabeçalho `typ: "agent+jwt"`, `alg`/ `kid` aceitos; declarações `iss: `, `sub: `, `aud: "https://api.singlefax.com"`, `iat` atual, `exp` dentro de 60 segundos e um `jti` novo. Chame `POST https://api.singlefax.com/api/auth/capability/execute` com `Authorization: Bearer ` e `{ "capability": "get_credits", "arguments": {} }`, ou outra capacidade concedida com os argumentos documentados. Essas credenciais são provas assinadas, não chaves de API nem tokens de acesso OAuth. 6. Para um novo código de dispositivo em um agente registrado, use `POST https://api.singlefax.com/api/auth/agent/device/code` com `{ "agent_id": "" }` e um JWT de host assinado. Este endpoint não pode registrar um agente. Revogue por `POST https://api.singlefax.com/api/auth/agent/revoke` com `{ "agent_id": "" }` e o JWT do host proprietário ou a sessão do proprietário. `send_fax` exige verificação do usuário com chave de acesso; não é autônomo. **Não** envie ID-JAGs nem `{ "type": "anonymous" }` via POST aqui. Esses tipos de identidade não são aceitos. ## Pagamentos de máquina (sem OAuth) O pagamento autônomo usa MPP HTTP 402 em `POST /api/v1/machine/faxes` com um Stripe Shared Payment Token ou Tempo USDC. Veja https://singlefax.com/mpp.md. O Cursor não pode gerar um SPT; use o Stripe Link CLI com essa URL REST, e não com `/mcp`. Carteiras Tempo pagam o desafio Tempo na mesma URL. ## HIPAA Não envie PHI pelo MCP, MPP ou API pública. Entidades cobertas usam o modo HIPAA Secure no site com um BAA eletrônico. [singlefax](https://singlefax.com/pt-br) Envie uma vez. Receba quando precisar. [![Disponível no Google Play](https://singlefax.com/images/google-play-badge.png)](https://play.google.com/store/apps/details?id=com.monocube.singlefax) [Adicionar ao Chrome](https://chromewebstore.google.com/detail/singlefax-fax-a-document/ojpmpilgkmjcfebhpkdmmjlkbcifkkej) [SingleFax no LinkedIn](https://www.linkedin.com/company/singlefax/) [SingleFax no Facebook](https://www.facebook.com/singlefax) [SingleFax no Instagram](https://www.instagram.com/singlefax.app) [SingleFax no Threads](https://www.threads.com/@singlefax.app) [SingleFax no YouTube](https://www.youtube.com/@singlefax) [SingleFax no GitHub](https://github.com/SingleFax) ## Serviços de fax - [Enviar um fax](https://singlefax.com/pt-br/enviar-fax?type=send) - [Receber fax](https://singlefax.com/pt-br/enviar-fax?type=receive) - [Número gratuito de 24 horas](https://singlefax.com/pt-br/numero-de-fax-gratis) - [Número vitalício](https://singlefax.com/pt-br/numero-de-fax-vitalicio) - [Portabilidade de número](https://singlefax.com/pt-br/portabilidade-numero-fax) - [Fax de teste](https://singlefax.com/pt-br/numero-de-fax-de-teste) - [Planos para empresas](https://singlefax.com/pt-br/para-empresas) - [HIPAA Secure](https://singlefax.com/pt-br/fax-hipaa) - [Fax pela internet](https://singlefax.com/pt-br/fax-pela-internet) - [Enviar fax por e-mail](https://singlefax.com/pt-br/enviar-fax-por-email) - [Do WhatsApp para fax](https://singlefax.com/pt-br/enviar-fax-pelo-whatsapp) ## Formulários do IRS - [Todos os formulários do IRS](https://singlefax.com/pt-br/formularios-irs) - [EIN · Formulário SS-4](https://singlefax.com/pt-br/obter-ein) - [Formulário 5472](https://singlefax.com/pt-br/enviar-formulario-5472) - [Formulário 7004](https://singlefax.com/pt-br/enviar-formulario-7004) - [Formulário 2553](https://singlefax.com/pt-br/enviar-formulario-2553) - [Formulário 2848](https://singlefax.com/pt-br/enviar-formulario-2848) - [Formulário 4506-T](https://singlefax.com/pt-br/enviar-formulario-4506-t) - [Formulário 8821](https://singlefax.com/pt-br/enviar-formulario-8821) - [Formulário 8802](https://singlefax.com/pt-br/enviar-formulario-8802) - [Formulário 8655](https://singlefax.com/pt-br/enviar-formulario-8655) - [Formulário 3911](https://singlefax.com/pt-br/enviar-formulario-3911) - [Formulário 8233](https://singlefax.com/pt-br/enviar-formulario-8233) - [NY POA-1](https://singlefax.com/pt-br/enviar-formulario-ny-poa-1) ## Ferramentas e recursos - [Ferramentas de fax gratuitas](https://singlefax.com/pt-br/ferramentas-fax-gratis) - [Preparar um PDF para fax](https://singlefax.com/pt-br/preparar-fax) - [Página de teste para impressão](https://singlefax.com/pt-br/pagina-de-teste-fax) - [Folhas de rosto](https://singlefax.com/pt-br/folha-de-rosto-fax) - [Aplicativo móvel](https://singlefax.com/pt-br/aplicativo-celular) - [Extensão do Chrome](https://singlefax.com/pt-br/extensao-chrome) - [Desenvolvedores](https://singlefax.com/pt-br/desenvolvedores) - [Fax para agentes de IA](https://singlefax.com/pt-br/agentes-ia) - [Versionamento](https://singlefax.com/pt-br/versionamento) - [Diretório de fax do Congresso](https://singlefax.com/pt-br/fax/congresso) - [Diretório de fax do Senado](https://singlefax.com/pt-br/fax/senado) - [Diretório de fax de governadores](https://singlefax.com/pt-br/fax/governadores) ## SingleFax - [Preços](https://singlefax.com/pt-br/precos) - [Blog](https://singlefax.com/pt-br/blog) - [Sobre](https://singlefax.com/pt-br/sobre) - [Contato](https://singlefax.com/pt-br/contato) - [Suporte](https://singlefax.com/pt-br/suporte) © 2026 SingleFax [Privacidade](https://singlefax.com/pt-br/politica-de-privacidade) [Termos](https://singlefax.com/pt-br/termos-de-servico) [Reembolsos](https://singlefax.com/pt-br/politica-de-reembolso) [Denunciar abuso](https://singlefax.com/pt-br/denunciar-abuso) ```json {"@context":"https://schema.org","@graph":[{"@id":"https://singlefax.com/pt-br#website","@type":"WebSite","description":"Com o SingleFax, você envia e recebe fax avulsos pelo celular ou computador. Não precisa se cadastrar nem criar uma conta.","inLanguage":"pt-BR","name":"SingleFax – Envie e receba fax avulsos","url":"https://singlefax.com/pt-br","translationOfWork":{"@id":"https://singlefax.com/#website"}},{"@id":"https://singlefax.com/pt-br/autenticacao#webpage","@type":"WebPage","description":"Autenticação SingleFax com chaves de API, MCP OAuth e Agent Auth delegado. URLs de descoberta, permissões, registro e uso de credenciais.","name":"Autenticação: chaves de API, OAuth e Agent Auth","url":"https://singlefax.com/pt-br/autenticacao","isPartOf":{"@id":"https://singlefax.com/pt-br#website"},"potentialAction":[{"@type":"ReadAction","target":["https://singlefax.com/pt-br/autenticacao"]}]}]} ```