Autenticación

Documentación para agentes: índice en https://api.staging.flowence.tech/connect/docs/llms.txt. La documentación completa requiere una credencial de Flowence Connect: la herramienta docs del servidor MCP o la clave API en el encabezado Authorization.

Cada pedido a Flowence Connect lleva una credencial. Hay dos tipos:

Conexiones OAuth

El usuario pega https://api.staging.flowence.tech/mcp en su asistente. El asistente descubre la autorización por su cuenta y abre Flowence en el navegador:

1. El usuario inicia sesión (con su segundo factor o passkey, si los usa).
2. Flowence muestra la pantalla de consentimiento: qué aplicación pide acceso, el dominio que publicó sus metadatos, a dónde vuelve, cuándo y desde qué IP se inició el pedido, con qué usuario y contexto se conectará, el nivel de acceso (solo lectura, o lectura y operación) y las áreas. Si usted no inició el pedido hace instantes, no lo autorice: alguien pudo haberle reenviado el enlace.
3. Al autorizar, el navegador vuelve al asistente, que obtiene sus tokens.

Solo Claude y ChatGPT figuran como aplicaciones conocidas (sus documentos de metadatos bajo https://claude.ai/oauth/ y https://chatgpt.com/oauth/). En cualquier otra, el nombre y el logo los declara la propia aplicación: autorice solo si usted inició la conexión y reconoce el dominio. Los dominios se muestran en punycode (xn--...), así un dominio con letras de otro alfabeto no puede pasar por uno conocido. El logo se muestra únicamente si lo sirve el mismo dominio que publicó los metadatos.

Si rechaza el pedido, Flowence vuelve a la aplicación con error=access_denied solo si es una aplicación conocida o se ejecuta en su computadora (dirección loopback). En cualquier otro caso muestra un aviso y no redirige.

Detalles técnicos para clientes MCP:

• Metadatos del recurso protegido (RFC 9728): https://api.staging.flowence.tech/.well-known/oauth-protected-resource/mcp.
• Metadatos del servidor de autorización (RFC 8414): https://api.staging.flowence.tech/.well-known/oauth-authorization-server.
• Código de autorización con PKCE S256 obligatorio, parámetro resource (RFC 8707) e iss en la respuesta (RFC 9207).
• Clientes públicos (token_endpoint_auth_method: none), identificados con Client ID Metadata Documents o registro dinámico (RFC 7591). El client_id de un documento de metadatos se acepta solo en ASCII: los dominios internacionales van en punycode (xn--...). Los documentos de metadatos y su jwks_uri se descargan solo por HTTPS en el puerto 443. El registro dinámico recibe application/json y el canje y la revocación, application/x-www-form-urlencoded. Un registro dinámico idéntico a uno anterior (mismas direcciones de retorno, nombre, URI y logo) recibe el mismo client_id.
• redirect_uri es obligatoria en /oauth/authorize y en el canje, y debe coincidir exactamente con una registrada. Las direcciones loopback (http://localhost, http://127.0.0.1 y http://[::1]) se comparan sin el puerto. Un esquema propio (por ejemplo cursor://) se acepta si es de un cliente conocido (cursor, vscode, vscode-insiders o windsurf) o tiene forma de dominio invertido (com.example.app:/callback); los que abren programas del sistema operativo se rechazan.
• Si una aplicación envía una client_assertion (por ejemplo ChatGPT, que declara private_key_jwt), Flowence la valida: JWT RS256 o ES256 firmado con una clave del JWKS de su documento de metadatos, iss y sub iguales al client_id, aud igual al emisor o al endpoint de token, vencimiento corto y jti de un solo uso si viene. Una aserción inválida recibe invalid_client. Sin aserción, el cliente se trata como público, igual que antes.
• Los errores anteriores al consentimiento (por ejemplo, falta PKCE o el alcance es desconocido) vuelven automáticamente a la aplicación solo si su dirección de retorno es loopback, o si es una aplicación conocida (Claude o ChatGPT) que vuelve a su propio dominio. En cualquier otro caso, Flowence muestra una página de error y no redirige.
• Alcances OAuth: flowence.read y flowence.write. El servidor MCP anuncia los dos, así que el cliente los pide y el usuario elige en el consentimiento: solo lectura (la opción marcada por defecto) o lectura y escritura.
• Token de acceso de 60 minutos y refresh token rotativo de 30 días; la conexión dura hasta 180 días.
• Rotación del refresh token: cada canje emite un par nuevo. Si el mismo refresh token se presenta otra vez dentro de los 30 segundos (por ejemplo, un reintento), la respuesta es el mismo par ya emitido; nunca otro. Si se presenta después de esa ventana, Flowence lo trata como posible robo y revoca la conexión completa.
• Código de autorización de un solo uso: si se presenta dos veces un pedido completo y válido (mismo client_id, redirect_uri y code_verifier correcto), se revoca la conexión. Un pedido repetido inválido solo recibe invalid_grant.
• Revocación: https://api.staging.flowence.tech/oauth/revoke (RFC 7009) o desde Flowence Connect → Conexiones. Un token vencido o ya revocado no revoca nada y, si el pedido incluye client_id, el token tiene que pertenecer a esa aplicación.
• Los tokens OAuth sirven solo en el servidor MCP. Para la API REST use una clave API.

Claves API

Crear una clave

1. En Flowence, vaya a Flowence Connect → Claves API → Nueva clave API. Hace falta el permiso "Administrar Flowence Connect".
2. Indique un nombre que identifique al agente o la integración (por ejemplo "Agente de cobranzas").
3. Elija los alcances (ver abajo), la vigencia (30, 90 o 365 días) y, si quiere, las IP o rangos desde los que se podrá usar.
4. Copie la clave. Se muestra una sola vez: Flowence guarda solo un hash.

La clave actúa en nombre del usuario que la crea (el usuario responsable) y conserva el contexto de empresa con que ese usuario inició sesión.

Formato

Después del prefijo vienen 40 caracteres alfanuméricos. Si una clave aparece en un repositorio o un registro, el prefijo permite detectarla y revocarla.

Cómo enviarla

Authorization: Bearer flw_live_...

También se acepta el encabezado X-API-Key: flw_live_.... Nunca la envíe en la URL: las claves en parámetros de consulta se rechazan.

Alcances

Los alcances limitan qué áreas puede usar la credencial. Toda credencial incluye companies:read, necesario para resolver proveedores y monedas.

Qué puede hacer realmente una credencial

El acceso efectivo es la intersección de tres cosas:

1. Los alcances de la credencial.
2. Los permisos del usuario responsable en Flowence (sus roles).
3. El alcance por proveedor del usuario: un operador que gestiona solo algunos proveedores ve solo esos proveedores, y no ve los deudores que tiene excluidos.

Por eso una credencial nunca puede más que su usuario responsable. Si al usuario le quitan un permiso, la credencial lo pierde en el acto. Si el usuario se desactiva o se bloquea, la credencial deja de funcionar. Lo mismo pasa si el usuario pierde el rol con que se creó la credencial (por ejemplo, pasa de administrador a operador): la credencial deja de funcionar y hay que crear otra con el rol actual, para que se aplique el alcance que corresponde.

Solo pueden ser responsables los usuarios con contexto de gestión (administrador, operador o supervisión). Los usuarios de portales (deudores, cadetes, distribuidores) no pueden crear credenciales.

Vencimiento, rotación y revocación

• Vencimiento. La clave deja de funcionar al vencer. status avisa cuando faltan menos de 7 días.
• Rotación. Cree una clave nueva, actualice el agente y revoque la anterior.
• Revocación. En Flowence Connect → Claves API, use Revocar. El efecto es inmediato: la caché de autenticación se descarta al revocar y otra vez cuando se confirma el cambio, así que el pedido siguiente ya se rechaza.
• Actividad. En Flowence Connect → Actividad se ve cada pedido: operación, resultado, IP y cliente.

Restricción por IP

Si indica IP o rangos (por ejemplo 203.0.113.10 o 203.0.113.0/24, separados por coma), los pedidos desde otras direcciones se rechazan con 401.

Errores de autenticación

La respuesta 401 no indica el motivo concreto. Si la credencial existe (por ejemplo, está revocada, vencida o se usa desde una IP no permitida), el rechazo queda en Flowence Connect → Actividad del tenant, con la credencial y el usuario responsable: lo ven quien administra Flowence Connect y el propio usuario. Una credencial desconocida no tiene tenant al que atribuirla y no aparece en la actividad del tenant.

Ante insufficient_scope o forbidden, el agente debe explicar al usuario qué acceso falta; no debe intentar rodearlo. Vea Límites y errores.

Con OAuth, cuando la conexión no tiene el nivel que pide la acción (por ejemplo, se conectó solo para lectura y la acción es de escritura), el servidor MCP pide volver a autorizar: responde 403 con WWW-Authenticate: Bearer error="insufficient_scope" y, en ChatGPT, un resultado de herramienta con el mismo desafío en _meta["mcp/www_authenticate"]. Si la conexión ya tiene ese nivel pero el usuario no marcó el área al aprobar, no hay desafío: el error indica el área (details.area) y hay que desconectar y volver a conectar marcándola. Vea Límites y errores.

El acceso también respeta el alcance del usuario responsable: si es un operador, solo ve y opera los proveedores que tiene asignados, sin los deudores excluidos.