Skip to main content
Crear una aplicación la registra. Configurarla es lo que la hace funcionar. Esta página recorre las cuatro pestañas del editor de la app en el orden en que debes completarlas y explica qué controla cada campo. Asegura estos puntos antes de construir tu flujo de autorización: la mayoría de las fallas de integración OAuth se deben a una desconfiguración, no al código.
Llega al editor desde ‘Tus apps’ en el panel para desarrolladores, o directamente en https://fluz.app/for-developers/overview/{appId}. Los widgets embebidos usan las mismas pestañas más una pestaña adicional de Instalación: consulta Configurar widget de la app.
Seleccionar una app para configurar desde Tus apps

​
Qué hay en cada pestaña

​
Pestaña Overview

Aquí viven dos cosas que sirven a públicos muy distintos.

​
Tus credenciales

El Client ID y el Client Secret están en esta pestaña. Cada otra página en esta sección que te diga que autentiques una solicitud con Authorization: Basic base64(client_id:client_secret) se refiere a estos valores. El API Key y el API Secret también están aquí: son otro par con otra función. Consulta Aplicaciones OAuth para saber qué credencial hace qué.Cópialos a tu gestor de secretos. Nunca a un bundle del navegador, un binario móvil o control de versiones.

​
Tu identidad pública

El nombre, subtítulo, descripción, avatar y logomark son lo que ven tus usuarios en la pantalla de consentimiento cuando deciden si entregan a tu aplicación acceso a su dinero. Trátalos como copy de producto, no como etiquetas internas.
Revisa esta pestaña incluso si crees que la completaste durante la creación. Los tres campos de texto se recopilan en el asistente de creación, donde es fácil escribir un placeholder y seguir — y luego terminar publicándolo en una pantalla de consentimiento.

​
Pestaña Permissions

Esta pestaña define los permisos que tu aplicación pide. No es lo que te ha otorgado ningún usuario en particular: eso llega en el intercambio de token. Como la pantalla de consentimiento se construye a partir de esta pestaña y no de tu URL de autorización, lo que selecciones aquí es exactamente lo que se le pide aprobar a cada usuario. No hay forma de acotarlo por solicitud. La pestaña contiene dos listas de permisos independientes: Selección de alcances en la pestaña Permissions

​
Cómo llegan los alcances seleccionados al usuario

Los usuarios no ven valores enum crudos. Los alcances que seleccionas se agrupan bajo un encabezado legible de nivel superior, y es ese encabezado el que se presenta para aprobación. Un alcance no marcado se omite por completo de lo que se le pide aprobar al usuario — y de lo que tu app podrá solicitar jamás. Cómo aparecen los alcances agrupados en la pantalla de consentimiento

​
Alcances requeridos

Algunos alcances son obligatorios para el tipo de app o widget que estás configurando: sin ellos el flujo físicamente no puede ejecutarse. Estos se reúnen al final de la pestaña. Los verás allí; no los eliges.
La pantalla de consentimiento presenta tus alcances seleccionados como una lista de solo lectura. El usuario acepta el conjunto completo o no completa la autorización; no hay casillas por alcance. Esto aplica a todos los alcances, no solo a los obligatorios, así que la distinción que antes importaba en la pantalla de consentimiento ya no aplica: todo lo que dejes marcado aquí, el usuario tendrá que aceptarlo.

​
Business permissions

Si tu aplicación atiende a empresas, completa también la lista Business permissions. Se edita de forma independiente de la lista de consumidor y no tiene restricciones de selección: un permiso puede estar en una lista, en la otra, en ambas o en ninguna.
  • El permiso para registrar una empresa no se ofrece aquí. Ese lo otorga la cuenta personal — es lo que permite a un usuario crear una empresa en primer lugar — así que pertenece a la lista Permissions. No aparecerá como opción en la lista de empresa.
  • Dejar esta lista vacía significa que la app no está habilitada para empresas. No se les ofrecerá a los usuarios la opción de solicitar una cuenta de empresa durante la autorización.
  • Las apps que ya existían antes de introducir esta lista se rellenaron con una copia de sus permisos de consumidor. Revísala en lugar de asumir que es lo que quieres.
Consulta Business Accounts in OAuth para ver cómo se aplican las dos listas en el momento de la autorización.

​
Capacidades de la app

​
Elegir tus alcances

Parte de lo que necesita el flujo que tienes delante, no de lo que podrías necesitar algún día. Referencia completa: Alcances de la aplicación.
Menos alcances convierten mejor. La pantalla de consentimiento es el paso con mayor abandono en tu integración, y su extensión la determina esta pestaña. Un techo más angosto también limita el radio de impacto si un token se filtra. Pide lo que necesita el flujo de hoy; amplía el techo cuando construyas la próxima función.

​
Alcances que no puedes auto-seleccionar

PCI_COMPLIANCE es administrado por Fluz a nivel de aplicación, se otorga a desarrolladores que han demostrado cumplimiento con PCI DSS y no puede solicitarse al generar un token. Si necesitas manejar datos de tarjeta crudos tú mismo, habla con tu account manager de Fluz. Si no quieres hacerlo, para eso están los widgets embebidos: mantienen la captura de tarjeta dentro del alcance PCI de Fluz.

​
Cambiar alcances más adelante

El modelo de permisos es una intersección del techo a nivel de app y la concesión de cada usuario, lo que tiene dos consecuencias prácticas:
  • Agregar un alcance aquí no lo otorga retroactivamente a los tokens que los usuarios ya te emitieron. Los usuarios existentes deben volver a autorizar antes de que el nuevo alcance sea efectivo para ellos.
  • Quitar un alcance aquí reduce el acceso efectivo de inmediato, para cada usuario, sin importar lo que aprobaron previamente.
Planea los cambios de alcances como migraciones de esquema, no como ajustes de configuración.

​
Pestaña OAuth

Configuración de Redirect URI en la pestaña OAuth

​
Origin

El dominio que alojará el flujo: example.com, app.example.com. Para widgets embebidos, esta es la página donde se renderiza el widget y debe coincidir o el widget no cargará.

​
Redirect URIs

A dónde nuestro servidor de autorización puede enviar al usuario después de que apruebe o rechace.
  • Debe ser una URL pública a la que nuestros servidores puedan acceder.
  • Sin parámetros de consulta en la URI registrada. Usa el parámetro state para portar contexto.
  • Registra tantas como necesites: una por ambiente, una por variante de flujo.
  • La URI que uses en /authorize debe estar registrada aquí, y la URI que envíes a /token/exchange debe ser idéntica a nivel de bytes a la que usaste en /authorize.
Estas son cuatro URIs distintas para el servidor de autorización:
Elige una forma canónica, guárdala en una sola constante y usa esa misma constante tanto en el paso de autorización como en el de intercambio. Codificarla dos veces es como ocurren las discrepancias.
Registra tu callback local explícitamente — por ejemplo http://localhost:3035/oauth/finalize. No funcionará a menos que esté en la lista, y las URIs de localhost no deben quedar registradas en una app de producción.

​
Webhook URLs

Endpoints REST públicos que reciben eventos de Fluz: cómo te enteras de que una transferencia se completó, un usuario cerró un modal o una verificación se resolvió, sin hacer polling.
  • Agrega tantas URLs como quieras.
  • Suscribe cada URL a eventos específicos, para que puedas encaminar diferentes familias de eventos a distintos servicios.
  • Una URL sin eventos seleccionados se vuelve un catch-all y recibe todo. Conveniente en desarrollo, ruidoso en producción.
Tu endpoint debe reconocer rápido y procesar de forma asíncrona. Haz el trabajo mínimo necesario para aceptar el evento y luego entrégalo a una cola: un handler de webhooks lento se convierte en un problema de entrega.

​
Verifica antes de construir

Cinco minutos aquí te ahorran una tarde depurando el flujo de autorización.
1

Las credenciales están fuera del dashboard y en tu almacén de secretos

Client ID, Client Secret, API Key, API Secret. Confirma que nada terminó en un .env que esté trackeado en git.
2

La pantalla de consentimiento se lee bien

Nombre, subtítulo, descripción, avatar y logomark, todo completado y escrito para tus usuarios.
3

Cada alcance que tu código invoca está marcado en Permissions

Recorre tus llamadas API previstas y confirma que el alcance de cada una esté habilitado — también en la lista Business permissions, si tu app atiende a empresas. Un alcance que nunca habilitaste aquí nunca se le ofrece al usuario, así que este error aparece después como un confuso error de permisos.
4

No hay nada marcado que no puedas justificarle a un usuario

La pantalla de consentimiento es ahora exactamente esta lista, de solo lectura. Cada alcance de más es una línea que el usuario tiene que aceptar para terminar.
5

Tu Redirect URI está registrada en su forma canónica exacta

Incluyendo protocolo, uso de mayúsculas en el host y la barra final.
6

Construye a mano una URL de autorización y ábrela

Arma /authorize con response_type=code, tu client_id y tu redirect_uri registrada, luego cárgala en un navegador. Si la pantalla de consentimiento se renderiza con tu branding y los alcances que esperas, tu configuración es correcta. Si da error, el mensaje nombra lo que no coincidió — y lo habrás encontrado antes de escribir código.→ Flujo de concesión OAuth de cara al cliente

​
Staging y producción son apps separadas

Los entornos no comparten configuración. Una aplicación de producción se registra por separado, con su propio Client ID, Client Secret, API Key y API Secret, y sus propias URIs de redirección y endpoints de webhooks apuntados a hosts en vivo. Nada se traslada desde staging, incluidos los alcances seleccionados. Vuelve a verificar toda esta página contra tu app de producción antes del lanzamiento. Consulta Implementación en producción.

​
Solución de problemas

​
Próximos pasos

Flujo de concesión de cara al cliente

Construye la URL de autorización y maneja el callback.

Intercambiar un código de autorización

Convierte un código en un access token y refresh token.

Alcances de la aplicación

La referencia completa de alcances.

Implementar en producción

Vuelve a registrar en hosts en vivo y sal a producción.