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.
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, ouhttpemlocalhost,127.0.0.1ou[::1](qualquer porta); - os escopos que ele pode pedir:
custom-functions:runpara 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ção | Valor |
|---|---|
| Endpoint de autorização | https://app.monochat.ai/oauth/authorize |
| Endpoint de token | https://app.monochat.ai/oauth/token |
| Endpoint de revogação | https://app.monochat.ai/oauth/revoke |
| Recurso | https://app.monochat.ai/api/custom-functions |
| Escopo | custom-functions:run |
| Autenticação do cliente | HTTP 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).
- Envie o usuário ao endpoint de autorização com
response_type=code, o seuclient_id, umaredirect_uriregistrada,scope=custom-functions:run,resource=https://app.monochat.ai/api/custom-functions, umstatee umcode_challengecomcode_challenge_method=S256. - 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.
- O MonoChat devolve o usuário à sua
redirect_uricomcode,stateeiss. Se o usuário clicar em Negar, ele enviaerror=access_deniedno lugar. - 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 '{}'
| Status | Quando |
|---|---|
401 | O 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. |
403 | A 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. |
429 | Um 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_tokene orefresh_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.