Pular para o conteúdo principal

OAuth para apps de parceiros

Um app de parceiro, uma ferramenta de automação ou um app personalizado que trabalha para um usuário do MonoChat pode chamar a API de funções personalizadas (POST https://app.monochat.ai/api/<slug>/custom-functions/<path>) com um token de acesso OAuth em vez de um token de API. O usuário aprova o app em uma página do MonoChat, escolhe as organizações que ele pode alcançar e pode revogá-lo a qualquer momento em Apps conectados nas configurações de perfil.

Os tokens de API continuam funcionando no mesmo endpoint. OAuth é a opção para um app que age por outras pessoas: ele nunca vê uma senha ou um token de API, e cada usuário pode desconectá-lo sozinho.

O app age como o usuário

Uma chamada feita com um token de acesso é executada como o usuário que aprovou o app, com os papéis dele. Ela executa apenas os métodos personalizados da organização, e só nas organizações em que o usuário é agente.

Obter um cliente​

Peça ao MonoChat um cliente para o seu app. O MonoChat o registra com:

  • o nome do app, mostrado na página de aprovação e em Apps conectados;
  • as URIs de redirecionamento, com correspondência exata: endereços https, ou http em localhost, 127.0.0.1 ou [::1] (qualquer porta);
  • os escopos que ele pode pedir: custom-functions:run para esta API.

Você recebe um ID do cliente (começa com monochat_rc_) e um segredo do cliente (começa com monochat_cs_). O segredo é mostrado uma única vez; o MonoChat guarda apenas o hash dele. Mantenha-o no seu servidor, nunca em um navegador ou em um app móvel.

Um app que não consegue guardar um segredo, como um que roda no navegador ou no computador do usuário, pode usar como ID do cliente a URL de um documento de metadados do cliente, como fazem os clientes MCP. Nesse caso, ele não envia segredo.

Endpoints​

Os metadados do servidor de autorização em https://app.monochat.ai/.well-known/oauth-authorization-server listam todos os endpoints. Em uma instalação white label ou auto-hospedada, use o endereço próprio dessa instalação.

ConfiguraçãoValor
Endpoint de autorizaçãohttps://app.monochat.ai/oauth/authorize
Endpoint de tokenhttps://app.monochat.ai/oauth/token
Endpoint de revogaçãohttps://app.monochat.ai/oauth/revoke
Recursohttps://app.monochat.ai/api/custom-functions
Escopocustom-functions:run
Autenticação do clienteHTTP Basic, ou client_id e client_secret no corpo da requisição

Os metadados do próprio recurso ficam em https://app.monochat.ai/.well-known/oauth-protected-resource/api/custom-functions.

Conectar um usuário​

O MonoChat usa o fluxo de código de autorização com PKCE (S256). O usuário precisa ter a verificação em duas etapas configurada (por e-mail ou app autenticador).

  1. Envie o usuário ao endpoint de autorização com response_type=code, o seu client_id, uma redirect_uri registrada, scope=custom-functions:run, resource=https://app.monochat.ai/api/custom-functions, um state e um code_challenge com code_challenge_method=S256.
  2. O usuário entra no MonoChat se necessário. A página de aprovação mostra o nome do seu app e Executar métodos personalizados em seu nome. O usuário pode escolher as Organizações que o app pode alcançar (todas as dele quando nenhuma é escolhida), digita o código de confirmação de 6 dígitos e clica em Permitir.
  3. O MonoChat devolve o usuário à sua redirect_uri com code, state e iss. Se o usuário clicar em Negar, ele envia error=access_denied no lugar.
  4. Troque o código no endpoint de token em até 5 minutos:
curl -X POST https://app.monochat.ai/oauth/token \
-u "<client_id>:<client_secret>" \
-d grant_type=authorization_code \
-d code=<code> \
-d redirect_uri=<redirect_uri> \
-d code_verifier=<code_verifier>

A resposta traz um access_token (começa com monochat_at_) válido por expires_in segundos (uma hora), um refresh_token (começa com monochat_rt_) e o scope concedido.

Chamar a API​

Envie o token de acesso como token bearer:

curl -X POST https://app.monochat.ai/api/<slug>/custom-functions/<path> \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{}'
StatusQuando
401O token é desconhecido, expirou ou foi revogado, ou foi emitido para outro recurso, como o servidor MCP. O cabeçalho WWW-Authenticate aponta para os metadados do recurso.
403A organização não está entre as que o usuário permitiu para o app, o usuário não tem acesso à organização, ou a concessão não inclui custom-functions:run.
429Um limite foi atingido; aguarde os segundos indicados em Retry-After. As chamadas são contadas por minuto: 120 por concessão e 1.200 por cliente, além do limite próprio da organização para este endpoint.

Renovar e revogar​

  • Renovar: antes de o token de acesso expirar, chame o endpoint de token com grant_type=refresh_token e o refresh_token. Cada renovação devolve um novo refresh token; use o novo. Um refresh token usado de novo mais de um minuto depois de ser substituído encerra a concessão.
  • Expiração: a concessão termina 90 dias depois da última renovação, quando o usuário a revoga em Apps conectados, ou quando o usuário altera ou redefine a senha. O usuário então precisa aprovar o app de novo.
  • Revogar: para desconectar um usuário, envie o token de acesso ou o refresh token ao endpoint de revogação com a autenticação do seu cliente:
curl -X POST https://app.monochat.ai/oauth/revoke \
-u "<client_id>:<client_secret>" \
-d token=<refresh_token>

Conectar o mesmo usuário ao seu app de novo substitui a concessão anterior dele.