Conecte-se com OAuth

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:

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:

{
  "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/<id> 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):

grant_type=authorization_code
client_id=<your client id>
code=<single-use authorization code>
redirect_uri=<exact registered redirect URI>
code_verifier=<original PKCE 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/<id>, 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:

{
  "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#

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.