Saltar al contenido principal

OAuth para apps de socios

Una app de un socio, una herramienta de automatización o una app personalizada que trabaja para un usuario de MonoChat puede llamar a la API de funciones personalizadas (POST https://app.monochat.ai/api/<slug>/custom-functions/<path>) con un token de acceso OAuth en lugar de un token de API. El usuario aprueba la app en una página de MonoChat, elige las organizaciones a las que puede llegar y puede revocarla en cualquier momento en Apps conectadas de su configuración de perfil.

Los tokens de API siguen funcionando en el mismo endpoint. OAuth es la opción para una app que actúa en nombre de otras personas: nunca ve una contraseña ni un token de API, y cada usuario puede cortarla por su cuenta.

La app actúa como el usuario

Una llamada hecha con un token de acceso se ejecuta como el usuario que aprobó la app, con sus roles. Solo ejecuta los métodos personalizados de la organización, y solo en organizaciones donde el usuario es agente.

Obtener un cliente​

Pida a MonoChat un cliente para su app. MonoChat lo registra con:

  • el nombre de la app, que muestran la página de aprobación y Apps conectadas;
  • sus URI de redirección, con coincidencia exacta: direcciones https, o http en localhost, 127.0.0.1 o [::1] (cualquier puerto);
  • los ámbitos que puede pedir: custom-functions:run para esta API.

Recibe un ID de cliente (empieza por monochat_rc_) y un secreto de cliente (empieza por monochat_cs_). El secreto se muestra una sola vez; MonoChat solo guarda su hash. Guárdelo en su servidor, nunca en un navegador ni en una app móvil.

Una app que no puede guardar un secreto, como una que se ejecuta en el navegador o en el ordenador del usuario, puede usar en su lugar la URL de un documento de metadatos de cliente como ID de cliente, como hacen los clientes MCP. En ese caso no envía ningún secreto.

Endpoints​

Los metadatos del servidor de autorización en https://app.monochat.ai/.well-known/oauth-authorization-server listan todos los endpoints. En una instalación de marca blanca o alojada por usted, use la dirección propia de esa instalación.

AjusteValor
Endpoint de autorizaciónhttps://app.monochat.ai/oauth/authorize
Endpoint de tokenhttps://app.monochat.ai/oauth/token
Endpoint de revocaciónhttps://app.monochat.ai/oauth/revoke
Recursohttps://app.monochat.ai/api/custom-functions
Ámbitocustom-functions:run
Autenticación del clienteHTTP Basic, o client_id y client_secret en el cuerpo de la solicitud

Los metadatos propios del recurso están en https://app.monochat.ai/.well-known/oauth-protected-resource/api/custom-functions.

Conectar a un usuario​

MonoChat usa el flujo de código de autorización con PKCE (S256). El usuario necesita tener configurada la verificación en dos pasos (por correo electrónico o con una app de autenticación).

  1. Envíe al usuario al endpoint de autorización con response_type=code, su client_id, una redirect_uri registrada, scope=custom-functions:run, resource=https://app.monochat.ai/api/custom-functions, un state y un code_challenge con code_challenge_method=S256.
  2. El usuario inicia sesión en MonoChat si hace falta. La página de aprobación nombra su app y muestra Ejecutar métodos personalizados en su nombre. El usuario puede elegir las Organizaciones a las que puede llegar la app (todas las suyas si no elige ninguna), introduce su código de confirmación de 6 dígitos y hace clic en Permitir.
  3. MonoChat devuelve al usuario a su redirect_uri con code, state e iss. Si el usuario hace clic en Denegar, envía error=access_denied en su lugar.
  4. Canjee el código en el endpoint de token en un plazo de 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>

La respuesta contiene un access_token (empieza por monochat_at_) válido durante expires_in segundos (una hora), un refresh_token (empieza por monochat_rt_) y el scope concedido.

Llamar a la API​

Envíe el token de acceso 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 '{}'
EstadoCuándo
401El token es desconocido, ha caducado o se ha revocado, o se emitió para otro recurso, como el servidor MCP. La cabecera WWW-Authenticate apunta a los metadatos del recurso.
403La organización no es una de las que el usuario permitió para la app, el usuario no tiene acceso a la organización, o la autorización no incluye custom-functions:run.
429Se alcanzó un límite; espere los segundos indicados en Retry-After. Las llamadas se cuentan por minuto: 120 por autorización y 1.200 por cliente, además del límite propio de la organización para este endpoint.

Actualizar y revocar​

  • Actualizar: antes de que caduque el token de acceso, llame al endpoint de token con grant_type=refresh_token y el refresh_token. Cada actualización devuelve un nuevo token de actualización; use el nuevo. Un token de actualización usado de nuevo más de un minuto después de ser sustituido pone fin a la autorización.
  • Caducidad: la autorización termina 90 días después de su última actualización, cuando el usuario la revoca en Apps conectadas, o cuando el usuario cambia o restablece su contraseña. El usuario tendrá entonces que aprobar la app de nuevo.
  • Revocar: para desconectar a un usuario, envíe el token de acceso o de actualización al endpoint de revocación con la autenticación de su cliente:
curl -X POST https://app.monochat.ai/oauth/revoke \
-u "<client_id>:<client_secret>" \
-d token=<refresh_token>

Conectar de nuevo al mismo usuario con su app sustituye su autorización anterior.