--- title: "Conecte-se com OAuth" description: "Autorize clientes MCP e a CLI do ThunderPhone sem compartilhar uma chave de API." --- OAuth permite que um aplicativo se conecte a uma organização do ThunderPhone com as permissões que você aprovar. Clientes de diretório devem usar OAuth por padrão. As chaves de API da organização continuam disponíveis para clientes que exigem um token Bearer configurado manualmente. ## Aprovar uma conexão Inicie a conexão no seu cliente MCP. Entre no ThunderPhone, verifique o nome do aplicativo e as permissões solicitadas, escolha uma organização e selecione **Aprovar**. Selecione **Negar** se você não iniciou a conexão ou não confia no aplicativo. Os nomes dos aplicativos são fornecidos por seus desenvolvedores e não são um selo de verificação. As permissões de leitura expõem os dados nomeados, incluindo gravações e transcrições quando `calls:read` é solicitado. As permissões de escrita podem alterar ou excluir recursos; chamadas, campanhas, compras de números de telefone e implantações podem gerar custos ou afetar a produção. Sua função na organização continua se aplicando. Para uma conexão por CLI, abra o link de verificação exibido no terminal, compare o código de oito caracteres, selecione sua organização e aprove. Apenas abrir o link não concede acesso. Os códigos expiram após 15 minutos. ## Desconectar um aplicativo Abra **Organização → Chaves de API → Aplicativos autorizados** no painel e escolha **Revogar**. Isso revoga a autorização selecionada para a organização atual, incluindo os tokens de acesso e de atualização. Reconecte-se pelo aplicativo se quiser autorizá-lo novamente. ## Descoberta para clientes MCP Use a URL do servidor `https://api.thunderphone.com/v1/mcp`. Uma solicitação sem autenticação válida recebe `401` com: ```http WWW-Authenticate: Bearer resource_metadata="https://api.thunderphone.com/.well-known/oauth-protected-resource" ``` Busque esse documento e, em seguida, busque os metadados do servidor de autorização em `https://api.thunderphone.com/.well-known/oauth-authorization-server`. Os metadados do recurso também estão disponíveis em `/.well-known/oauth-protected-resource/v1/mcp`. Use os endpoints retornados em vez de construí-los. O identificador do recurso é `https://api.thunderphone.com/v1/mcp`. O servidor oferece suporte a código de autorização com **PKCE S256**, tokens de atualização rotativos, registro público dinâmico de clientes, revogação e concessão de autorização de dispositivo. Não há segredos de cliente nem concessões implícitas. A descoberta do OpenID também está disponível em `/.well-known/openid-configuration`; ela inclui os mesmos campos do servidor de autorização, além de `subject_types_supported: ["public"]` e o endpoint userinfo. Tokens de ID e Documentos de Metadados de ID de Cliente (CIMD) não são compatíveis. ### Registrar um cliente público Envie JSON para `POST /v1/oauth/register`: ```json { "client_name": "My MCP client", "redirect_uris": ["http://127.0.0.1:8765/callback"], "token_endpoint_auth_method": "none", "grant_types": ["authorization_code", "refresh_token"], "response_types": ["code"] } ``` Salve o `client_id` retornado. Os redirecionamentos devem usar HTTPS ou HTTP em `127.0.0.1` ou `localhost`. Registre a URI de retorno exata, incluindo a porta e o caminho. Fragmentos e credenciais incorporadas são rejeitados. Os valores opcionais `client_uri` e `logo_uri` devem usar HTTPS; o ThunderPhone não os busca durante o registro. O registro tem limite de taxa. Clientes registrados não expiram e permanecem registrados quando uma conexão é revogada. Os retornos HTTPS incluem `https://chatgpt.com/connector/oauth/` e `https://chatgpt.com/connector_platform_oauth_redirect`. Cada conexão pode registrar seu próprio cliente. ### Código de autorização Abra o endpoint de autorização descoberto com `client_id`, o `redirect_uri` registrado exato, `response_type=code`, um `state` aleatório, `scope`, `code_challenge`, `code_challenge_method=S256` e `resource=https://api.thunderphone.com/v1/mcp`. Calcule o desafio como o resumo SHA-256 em base64url sem preenchimento de um verificador PKCE novo e de alta entropia. Verifique o `state` e o `iss` retornados antes de trocar o código. Todas as respostas de autorização, incluindo negação e erros de protocolo, identificam o emissor com `iss`, correspondendo exatamente ao `issuer` descoberto. Erros de cliente ou retorno inválido são retornados localmente sem redirecionar para esse retorno. Faça a troca em `POST /v1/oauth/token` usando codificação de formulário (JSON também é aceito): ```text grant_type=authorization_code client_id= code= redirect_uri= code_verifier= resource=https://api.thunderphone.com/v1/mcp ``` O parâmetro opcional `resource` é aceito em solicitações de autorização e de token (incluindo trocas de atualização e de dispositivo). Quando omitido, seu padrão é o recurso MCP descoberto. Quando presente, ele deve corresponder exatamente a esse recurso; outros valores retornam `invalid_target`. Os tokens de acesso contêm esse público, e o MCP rejeita tokens sem público ou com público diferente com `401` e um desafio de descoberta. Solicitações e códigos de autorização expiram após 10 minutos. Todas as respostas de token contêm `access_token`, `token_type` (`Bearer`), `expires_in` (3600 segundos por padrão), `refresh_token`, `scope`, `organization_id` e `organization_name`. Envie tokens de acesso apenas pelo cabeçalho `Authorization: Bearer`. Nunca coloque tokens em URLs, logs, controle de versão ou chat. ### Atualizar e revogar Atualize com `grant_type=refresh_token`, `client_id`, `refresh_token` e `resource` no endpoint de token. Salve o novo token de atualização atomicamente e pare de usar o antigo. Tokens de atualização expiram após 30 dias sem uma atualização bem-sucedida. Um `scope` opcional pode restringir as permissões concedidas. `offline_access` é sempre incluído e tokens de atualização são sempre emitidos. Uma solicitação inicial sem `scope` concede apenas `offline_access`, portanto os clientes devem solicitar as permissões de que precisam. A reutilização de código e a reutilização de token de atualização rotativo revogam toda a autorização. Serialize as atualizações dentro de um cliente; repetir uma credencial trocada com sucesso não é uma estratégia segura de nova tentativa. Para desconectar, envie `token` e `client_id` para `POST /v1/oauth/revoke`. Revogar qualquer um dos tokens revoga sua autorização, incluindo todos os tokens emitidos a partir dele. Um token desconhecido retorna sucesso sem revelar se ele existe. Sessões do painel podem listar suas próprias autorizações em `GET /v1/oauth/grants` e revogar uma em `DELETE /v1/oauth/grants/`, com `X-ThunderPhone-Org` selecionando a organização. ### Autorização de dispositivo A autorização de dispositivo é restrita a clientes pré-registrados; clientes registrados dinamicamente recebem `unauthorized_client`. O cliente público pré-registrado `thunderphone-cli` oferece suporte a autorização de dispositivo e atualização. Envie `client_id=thunderphone-cli` e `scope` para `POST /v1/oauth/device/code`. Exiba `user_code` e `verification_uri` para a pessoa usuária ou abra `verification_uri_complete`. Consulte o endpoint de token com `grant_type=urn:ietf:params:oauth:grant-type:device_code`, `client_id` e `device_code`, aguardando pelo menos o `interval` retornado (5 segundos). Continue em `authorization_pending`. Em `slow_down`, use o novo `interval` retornado na resposta (aumentado em 5 segundos) para cada solicitação subsequente. Pare em `access_denied`, `expired_token` ou qualquer outro erro. Nunca aprove um código de dispositivo automaticamente. O cliente pré-registrado `thunderphone-mcp` aceita `http://127.0.0.1/callback` e `http://localhost/callback` em qualquer porta. Esquema, host, caminho e consulta devem corresponder; a troca de token deve usar a URI de redirecionamento exata (incluindo a porta) da autorização. Clientes registrados dinamicamente exigem correspondência exata da URI de redirecionamento, incluindo a porta. Registre dinamicamente um retorno diferente se precisar de outro caminho. ### Verificações de identidade da conta e domínio do workspace Solicite `openid email` juntamente com os escopos de operação de que seu cliente precisa. Chame o `userinfo_endpoint` descoberto (`GET /v1/oauth/userinfo`) com o token de acesso no cabeçalho Bearer. Uma resposta bem-sucedida contém: ```json { "sub": "123", "email": "person@example.com", "email_verified": true, "name": "Example User", "org_id": 456 } ``` `sub` é o identificador estável da pessoa usuária; `org_id` é a organização selecionada durante o consentimento. O endpoint exige ambos os escopos de identidade e retorna `403` se algum estiver ausente. Ele retorna `403` com `error=access_denied` se a conta não tiver um perfil de e-mail verificado, em vez de afirmar que um e-mail não verificado é confiável. Tokens inválidos, expirados, revogados ou com público incorreto retornam `401`. Tokens de sessão humana e chaves de API da organização não podem chamar userinfo. Nenhum token de ID é emitido. ## Permissões disponíveis | Categoria | Escopos | | --- | --- | | Agentes e importações de agentes | `agents:read`, `agents:write` | | Chamadas | `calls:read`, `calls:write` | | Números de telefone, quem liga bloqueado e VoIP | `numbers:read`, `numbers:write` | | Conhecimento | `knowledge:read`, `knowledge:write` | | Campanhas | `campaigns:read`, `campaigns:write` | | Integrações, endpoints de webhook, servidores MCP | `integrations:read`, `integrations:write` | | Vozes | `voices:read` | | Cenários de teste, execuções de teste, validação | `testing:read`, `testing:write` | | Faturamento | `billing:read` | | Identidade da conta e e-mail verificado | `openid`, `email` (ambos obrigatórios para userinfo) | | Conexão persistente | `offline_access` (sempre incluído) | GET, HEAD e OPTIONS usam escopos de leitura; outros métodos usam escopos de gravação. Alterações de voz e cobrança não estão disponíveis por OAuth; `POST /v1/voices/preview` usa `voices:read` porque visualiza uma voz sem alterar sua configuração. As ferramentas MCP aplicam o escopo da respectiva operação REST subjacente. Transferências entre organizações são negadas mesmo quando a pessoa que autoriza pertence a ambas as organizações. Outras famílias de API, incluindo gerenciamento de chaves de API e configurações de contas humanas, não estão disponíveis por OAuth. Uma permissão ausente em uma operação REST retorna `403` com `WWW-Authenticate: Bearer error="insufficient_scope", scope="..."`. Tokens de acesso inválidos ou expirados retornam `401`. ### Sinais de autenticação de ferramentas MCP Cada ferramenta em `tools/list` inclui `securitySchemes: [{"type": "oauth2", "scopes": ["agents:read"]}]`, com o escopo da operação REST dessa ferramenta. Ferramentas públicas de documentação usam uma lista de escopos vazia e ainda exigem uma conexão autenticada. Um token válido sem o escopo de uma ferramenta recebe HTTP `200` com um `result` JSON-RPC contendo `isError: true`, texto explicativo em `content` e `_meta["mcp/www_authenticate"]`. Este último é uma matriz que contém um desafio Bearer com `resource_metadata`, `error="insufficient_scope"`, `error_description` e o `scope` obrigatório. A ferramenta não é executada. Use esse desafio para solicitar consentimento ampliado. Autenticação ausente ou inválida continua retornando HTTP `401` com `WWW-Authenticate`; falhas de escopo REST continuam retornando HTTP `403`. ## Retenção de credenciais A API executa `python manage.py oauth_cleanup` a cada hora nos ambientes de homologação e produção. Ele remove solicitações de autorização e códigos de dispositivo expirados. Tokens de acesso expirados, códigos de autorização e hashes de tokens de atualização são removidos somente após sua concessão ser revogada ou toda a família estar inativa. Hashes já usados são mantidos enquanto a família tiver um token de atualização, código de autorização, código de dispositivo aprovado ou token de acesso utilizável, para que a limpeza não possa desativar a detecção de repetição.