Por qué existe OAuth aquí
Tu aplicación ya puede hacer todo lo que ofrece la API de Fluz en tu propia cuenta. Generas un token con tu clave de API y listo — ver Autenticación y Credenciales de API. Una aplicación OAuth es lo que necesitas cuando la cuenta no es tuya. En el momento en que quieras emitir una tarjeta en la billetera de un cliente, extraer de su cuenta bancaria vinculada, leer sus transacciones o pagarle, necesitas el permiso explícito de esa persona — y lo necesitas en una forma que Fluz pueda verificar, acotar (scope), expirar y revocar. Eso es una aplicación OAuth: una identidad registrada para tu software, más un mecanismo de consentimiento que convierte la aprobación de un usuario en un token que tu servidor puede usar.Una vez que tengas un token con alcance al cliente, la API es idéntica.
createVirtualCard con tu propio token crea una tarjeta en tu billetera; la misma mutación con un token del cliente la crea en la suya. OAuth cambia de quién es la cuenta que tocas, no lo que puedes hacer.¿Necesitas una?
- No — solo tu propia cuenta
- Sí — cuentas de clientes
- Ya tienes una
Estás emitiendo tarjetas, comprando tarjetas de regalo o moviendo dinero dentro de tu propia cuenta de Fluz: un motor de desembolsos, una corrida de tarjetas en lote, una herramienta interna de gasto, una sincronización de ERP.Usa la clave de API de tu aplicación para llamar
generateUserAccessToken directamente. Sin app OAuth, sin pantalla de consentimiento, sin redirección. Comienza en Credenciales de API.Tres conjuntos de credenciales, tres trabajos distintos
La fuente de confusión más común en esta sección es que una aplicación de Fluz lleva más de un par de credenciales, y no son intercambiables.El modelo de permisos
Fluz aplica permisos en dos niveles, y el acceso efectivo de una aplicación es la intersección de ambos.1
Otorgamiento a nivel de app — el techo
Configurado en la pestaña Permissions de tu app. Este es el máximo que tu aplicación podrá solicitar jamás, independientemente de cualquier usuario. Un scope que no hayas habilitado aquí se ignora silenciosamente si lo pones en una URL de authorize — la solicitud no fallará, simplemente no se otorgará ese scope.Algunos scopes son administrados por Fluz en lugar de ser autoseleccionados.
PCI_COMPLIANCE se otorga solo a nivel de aplicación, a desarrolladores que hayan demostrado cumplimiento con PCI DSS, y no puede solicitarse al generar un token.2
Otorgamiento a nivel de usuario — el piso
Configurado por el usuario final en la pantalla de consentimiento. Ven los scopes que solicitaste — agrupados bajo encabezados legibles de alto nivel en lugar de valores enum en crudo — y los aprueban. Cualquier cosa que rechacen no se otorga.
3
Ambos deben estar vigentes
Validado en
generateUserAccessToken, no en tiempo de llamada. Ambos otorgamientos deben existir y no haber expirado. Un otorgamiento revocado o vencido, por lo tanto, aparece como un fallo de generación de token, no como un error de permiso a mitad de un flujo — que suele ser el primer lugar a revisar cuando una integración que funcionaba deja de hacerlo.
Usa
getApplicationScopes para leer lo que está otorgado actualmente. Referencia completa: Application Scopes.
Pide menos. Una pantalla de consentimiento más corta convierte mejor, y un token más acotado limita el daño si se filtra. Solicita lo que el flujo frente a ti necesita y genera un token nuevo cuando necesites más.
El ciclo de vida, de extremo a extremo
Cada paso a continuación es una página de inmersión profunda en esta sección. Este es el mapa; las páginas son el territorio.1
Crea la app
Desde el panel de desarrollador, elige Browse templates y agrega la plantilla OAuth Integration. Ponle nombre, subtítulo y descripción — esos tres campos son lo que tus usuarios verán en la pantalla de consentimiento, así que escríbelos para un humano, no para tu issue tracker.→ Crear una app OAuth
2
Configúrala
En la pestaña Permissions, selecciona tu techo de scopes. En la pestaña OAuth, configura tus Redirect URIs (públicas, sin parámetros de query, cualquier cantidad de ellas) y tus Webhook URLs (cada una opcionalmente suscrita a eventos específicos; una URL sin ninguno seleccionado se convierte en catch-all). Agrega un avatar y un logomark en Overview — la pantalla de consentimiento se ve incompleta sin ellos.→ Configurar app OAuth
3
Envía al usuario a autorizar
Redirige a
/authorize con response_type=code, tu client_id, un redirect_uri registrado, una lista de scopes delimitada por espacios y un valor opcional state que quieres que te devuelvan intacto.→ Flujo de otorgamiento OAuth orientado al cliente4
Recibe el código
Tras la aprobación, Fluz redirige a tu
redirect_uri con code y tu state original. En caso de una mala configuración, la redirección lleva un mensaje de error que describe lo que no coincidió.5
Intercambia el código por tokens
Llama a
/token/exchange con el code y el mismo redirect_uri exacto, autenticado con Authorization: Basic base64(client_id:client_secret). Recibirás un accessToken, un refreshToken, marcas de tiempo de expiración y el arreglo de scopes confirmados.→ Intercambiar un código de autorización OAuth6
Refresca, no vuelvas a pedir permiso
Llama a
/token/refresh con el refresh_token y el mismo encabezado Basic auth. Los access tokens son deliberadamente de corta duración — del orden de diez minutos — mientras que los refresh tokens duran aproximadamente un mes. Refresca silenciosamente en segundo plano; solo vuelve a enviar a un usuario por consentimiento cuando el refresh token haya expirado o el otorgamiento haya sido revocado.→ Refrescar un OAuth accessToken7
Pasa a producción
Staging y producción son entornos separados con aplicaciones y credenciales separadas. Nada se traslada — registras la app, los Redirect URIs y los endpoints de webhook nuevamente contra los hosts de producción.→ Despliegue a producción
Reglas que muerden
Vale la pena interiorizarlas antes de comenzar, porque cada una de estas falla de forma silenciosa o confusa.Los Redirect URIs deben coincidir exactamente — dos veces
Los Redirect URIs deben coincidir exactamente — dos veces
El
redirect_uri que envías a /authorize debe estar registrado en tu app, y el que envías a /token/exchange debe ser idéntico byte a byte al que usaste en /authorize. Las barras finales, http vs https, y el uso de mayúsculas en el host cuentan. No registres parámetros de query en el propio URI — usa state para llevar contexto.Los scopes no habilitados se ignoran, no se rechazan
Los scopes no habilitados se ignoran, no se rechazan
Si solicitas un scope que no marcaste en la pestaña Permissions, la solicitud de authorize igual tendrá éxito — el scope se descartará. Lee siempre el arreglo
scope en la respuesta del intercambio y trátalo, no a tu solicitud, como la verdad sobre lo que puedes hacer.Un código de autorización es de un solo uso y corta vida
Un código de autorización es de un solo uso y corta vida
Intercámbialo inmediatamente, del lado del servidor, una sola vez. Si tu manejador de redirección puede reproducirse — un usuario refrescando la página de callback, un prefetcher de enlaces — asegúrate de que un segundo intento no corrompa el estado.
La autenticación Basic es base64 del par, no de cada parte
La autenticación Basic es base64 del par, no de cada parte
Authorization: Basic <base64(client_id + ":" + client_secret)>. Codifica la cadena unida. La mayoría de los fallos de integración en el paso de intercambio se deben a esto.`state` es tu único canal de retorno
`state` es tu único canal de retorno
La redirección es una navegación de navegador nueva. Si necesitas saber qué usuario, qué flujo o a qué página regresar, pon una referencia firmada o buscada por el servidor en
state. No pongas nada sensible allí — viaja a través del navegador del usuario.Las fallas de token suelen ser fallas de otorgamiento
Las fallas de token suelen ser fallas de otorgamiento
Si
generateUserAccessToken empieza a fallar para un usuario que funcionaba ayer, verifica si el otorgamiento a nivel de app o a nivel de usuario expiró o fue revocado, antes de revisar tu código.Apps OAuth vs. widgets
Ambas son aplicaciones. Ambas usan el modelo de permisos anterior. La diferencia es quién construye la superficie de consentimiento.
Puedes combinarlos: registra y realiza KYC de usuarios vía API, luego abre un widget solo para consentimiento y captura sensible. Ver Widgets incrustados para los patrones híbridos.
Próximos pasos
Crear una app OAuth
Registra tu aplicación desde la plantilla OAuth Integration.
Configurar app OAuth
Scopes, redirect URIs, webhooks, branding.
Flujo de otorgamiento orientado al cliente
Construye la URL de authorize y maneja el callback.
Intercambiar un código de autorización
Convierte un código en un access token y un refresh token.
Refrescar un access token
Mantente autorizado sin volver a pedir permiso al usuario.
Despliegue a producción
Vuelve a registrar contra hosts en vivo y sal a producción.
¿Estás construyendo una plataforma donde cada uno de tus clientes tiene una cuenta de Fluz? Crear una plataforma recorre todo el patrón de extremo a extremo, y cada capacidad en Características de la API funciona de manera idéntica en una cuenta conectada.