Configurar aplicación OAuth

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	Qué controla	Léela antes de
Overview	La identidad pública de tu app y dónde viven tus credenciales	Escribir cualquier código
Permissions	Los alcances máximos que tu app podrá solicitar jamás	Construir la URL de autorización
OAuth	Origen, URIs de redirección, endpoints de webhooks	Manejar el callback
Installation	Código de inserción generado (solo widgets)	Incrustar el widget

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.

Campo	Guía
App name	El nombre por el que ya te conocen tus usuarios. “Acme Payouts”, no “acme-oauth-prod-v2”.
Subtitle	Una línea sobre lo que la app hace por ellos.
Description	Un breve relato en lenguaje simple de por qué estás pidiendo acceso.
Avatar	Requerido en la práctica. Una pantalla de consentimiento con avatar en blanco luce inconclusa y los usuarios dudan.
Logomark	Agrégalo junto con el avatar.

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 establece tu techo de alcances: el conjunto máximo de permisos que tu aplicación podrá solicitar jamás a cualquier usuario. No es lo que te ha otorgado ningún usuario en particular. 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

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, y el usuario no puede deseleccionarlos en la pantalla de consentimiento. Los verás allí; no los eliges.

Elegir tus alcances

Parte de lo que necesita el flujo que tienes delante, no de lo que podrías necesitar algún día.

Si tu integración…	Solicita aproximadamente
Paga a usuarios desde tu plataforma	`MAKE_WITHDRAW`, `LIST_PAYMENT`
Cobra fondos a usuarios	`MAKE_DEPOSIT`, `LIST_PAYMENT`
Emite tarjetas en la billetera de un usuario	`CREATE_VIRTUALCARD`, `EDIT_VIRTUALCARD`, `REVEAL_VIRTUALCARD`
Distribuye tarjetas por enlace	`CREATE_VIRTUALCARD`, `CREATE_SHARE_LINK`
Vende o canjea tarjetas de regalo	`LIST_OFFERS`, `PURCHASE_GIFTCARD`, `REVEAL_GIFTCARD`, `LIST_PURCHASES`
Administra las fuentes de fondos de un usuario	`LIST_PAYMENT`, `MANAGE_PAYMENT`

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

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.

Reglas

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.

Idéntica a nivel de bytes significa idéntica a nivel de bytes

Estas son cuatro URIs distintas para el servidor de autorización:

https://app.example.com/oauth/finalize
https://app.example.com/oauth/finalize/
http://app.example.com/oauth/finalize
https://App.Example.com/oauth/finalize

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.

Desarrollo local

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.

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.

La pantalla de consentimiento se lee bien

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

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. Un alcance que solicitas pero no has habilitado aquí se descarta en silencio, no se rechaza: este error aparece después como un confuso error de permisos.

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

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

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

Arma /authorize con response_type=code, tu client_id, tu redirect_uri registrada y tus alcances, 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

Síntoma	Casi siempre
`/authorize` devuelve un error en lugar de una pantalla de consentimiento	`redirect_uri` no está registrada, o `client_id` no coincide con esta app
La pantalla de consentimiento muestra menos alcances de los que solicitaste	Los que faltan no están marcados en la pestaña Permissions
El intercambio en `/token/exchange` falla	`redirect_uri` no coincide a nivel de bytes con el paso de autorización, o el header de Basic auth codifica las partes por separado en lugar de `base64(client_id:client_secret)`
Una llamada API falla por un permiso que creías tener	El alcance está habilitado a nivel de app pero no estaba en la concesión de este usuario: revisa el arreglo `scope` devuelto por el intercambio, no lo que solicitaste
`generateUserAccessToken` falla para un usuario que antes funcionaba	La concesión a nivel de app o a nivel de usuario expiró o fue revocada. Ambas deben estar vigentes
El widget no carga en tu página	Origin no coincide con el dominio host
No llegan webhooks	La URL no es públicamente accesible o está suscrita a eventos distintos de los que se disparan

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.

​Qué hay en cada pestaña

​Pestaña Overview

​Tus credenciales

​Tu identidad pública

​Pestaña Permissions

​Cómo llegan los alcances seleccionados al usuario

​Alcances requeridos

​Elegir tus alcances

​Alcances que no puedes auto-seleccionar

​Cambiar alcances más adelante

​Pestaña OAuth

​Origin

​Redirect URIs

​Webhook URLs

​Verifica antes de construir

​Staging y producción son apps separadas

​Solución de problemas

​Próximos pasos

Flujo de concesión de cara al cliente

Intercambiar un código de autorización

Alcances de la aplicación

Implementar en producción

Qué hay en cada pestaña

Pestaña Overview

Tus credenciales

Tu identidad pública

Pestaña Permissions

Cómo llegan los alcances seleccionados al usuario

Alcances requeridos

Elegir tus alcances

Alcances que no puedes auto-seleccionar

Cambiar alcances más adelante

Pestaña OAuth

Origin

Redirect URIs

Webhook URLs

Verifica antes de construir

Staging y producción son apps separadas

Solución de problemas

Próximos pasos