Guía de Integración para Desarrolladores — Authorisation Server con RAR y Grant Management

---

Introducción y Visión General

La solución de Open Finance de Sensedia Chile implementa un Authorisation Server basado en el perfil de seguridad FAPI 2.0 y en las especificaciones internacionales:

• RFC 9126 — Pushed Authorization Requests (PAR): Los parámetros de autorización se envían al servidor vía POST seguro, evitando la exposición en la URL del navegador.

• RFC 9396 — Rich Authorization Requests (RAR): Permite solicitudes de autorización granulares mediante el parámetro authorization_details, en lugar de scopes genéricos.

• Grant Management for OAuth 2.0: Introduce el concepto de grant_id para gestionar el ciclo de vida completo de los consentimientos (crear, actualizar, reemplazar, fusionar, consultar y revocar).

 

Roles en el Ecosistema

El SFA chileno define cuatro roles principales para los participantes del ecosistema de Open Finance:

Rol	Sigla	Descripción
Institución Proveedora de Información	IPI	Entidad que almacena datos de clientes y los expone vía API.
Institución Proveedora de Cuentas	IPC	Entidad que aloja cuentas y procesa transacciones de pago.
Proveedor de Servicios Basados en Información	PSBI	Tercero receptor de datos (agregador financiero).
Proveedor de Servicios de Iniciación de Pagos	PSIP	Empresa autorizada para iniciar pagos desde cuentas de clientes.

---

Arquitectura de Componentes

La solución se compone de varios componentes que, en conjunto, cubren los requisitos funcionales y no funcionales exigidos por la regulación chilena.

 

Componentes clave

• Sensedia API Management: Punto de entrada con soporte mTLS/TLS. Maneja rate limiting (60 TPM / 10 TPS por endpoint). Gobierna todas las APIs del ecosistema (edición, manejo, customización y capacidades de seguridad requeridas por el regulador).

• Motor de consentimiento: Gestiona el ciclo de vida del consentimiento (estados, aprobadores múltiples, expiración) en la visión de IPI y IPC. Grant Management es parte del módulo para administrar grant_id con operaciones de creación, consulta, alteración y cambios.

• Auth Server (FAPI 2.0): Implementa PAR, RAR, DCR/DCM y emite tokens OAuth 2.0 en el perfil regulatorio de Chile.

• IPI/PSBI Journey (en construcción): Solicita y consume los datos proporcionados por los IPI para ofrecer productos o servicios nuevos o mejorados a los usuarios finales. Remueve la complejidad de integración entre participantes del ecosistema.

• Cumplimiento regulatorio: La solución cubre los requisitos funcionales y no funcionales (almacenamiento en caché del directorio central, gestión de webhooks, gestión de certificados, entre otros) requeridos para los roles de IPI y IPC.

 

Directorio Central CMF

La oferta incluye integración con el Directorio Central de la CMF, almacenando caché de los datos para garantizar precisión en las consultas. Se implementan mecanismos de actualización del caché conforme a la regulación. La copia local del participante es una réplica obligatoria que cada PSBI, PSIP, IPI e IPC mantiene en su infraestructura.

 

Este flujo debe ejecutarse cada vez que exista un aviso de actualización y, por defecto, en caso de no haber aviso, con una frecuencia mínima de 8 horas para cumplir con los requisitos del Perfil de Seguridad y del Anexo 3.

La copia local no es solo una lista de participantes — es el conjunto completo de datos que alimenta todos los flujos OIDC/FAPI:

• Identificación de los participantes: datos legales y estados operativos (Activo/Normal, Activo/Mecanismo Alternativo, Inactivo/Desconectado, Suspendido, etc.).

• Certificados digitales: mTLS de transporte + JWS de firma, con sus kid, vigencia y estado (activo, obsoleto, revocado).

• JWKS públicos para validación cruzada (incluyendo el JWKS del propio Directorio para validar SSAs en DCR).

• Servidores de autorización: emisor, URL de openid-configuration, endpoints de PAR/token, soporte a DCR.

• Recursos API y versiones: familia (Accounts, Payments, etc.), ApiResourceId, ApiVersion, endpoints concretos.

---

Authorisation y Grant Management

El flujo para la gestión del consentimiento se divide en dos partes principales: OIDC (Autorización) y Gestión de Consentimiento. Ambos flujos, juntos, forman los pasos necesarios para la generación de credenciales de acceso a las APIs y, a continuación, la posibilidad de gestionar los tokens para el acceso a las APIs de Negocio.

Comencemos con OIDC: aunque es el nombre más técnico, podemos entender este flujo como el flujo inicial para la generación de credenciales.

 

Modelo de relación basado en entidades y API

Authorisation

Responsable de la autorización y emisión de tokens a partir del modelo OpenID Connect (OIDC).

Reglas OpenID Connect en el SFA chileno

El SFA adopta OIDC con una versión restringida por el Perfil FAPI 2.0 de la OpenID Foundation.

Permitidos:

• Authorization Code Flow con PAR + JAR + RAR — el camino estándar para todos los consentimientos con interacción del usuario.

• Refresh Token — solo si está asociado a un grant existente.

• DCR — Dynamic Client Registration para la primera interacción con el servidor.

 

Auth Server OIDC API Endpoints

Método	Endpoint	Descripción
POST	/par	Pushed Authorization Request con RAR
GET	/authorize	Redirect para autenticación y consentimiento
POST	/token	Intercambia code por access_token + grant_id
GET	/.well-known/openid-configuration	Discovery metadata
POST	/clients-registrations/openid-connect	Dynamic Client Registration

Grant Management — Ciclo de Vida del Consentimiento

El grant_id es el identificador único de cada consentimiento. Las acciones de grant_management_action permiten manipular un grant existente:

Acción	Descripción	Requiere auth del usuario
create	Genera nuevo consentimiento y grant_id	Sí
update	Extiende duración sin alterar scope	No (si solo vigencia)
replace	Sustituye permissions por un conjunto nuevo	Sí
merge	Combina permisos nuevos con existentes	Sí
query	Consulta estado actual	No
revoke	Cancela consentimiento e invalida tokens	No

Estados del Consentimiento

Estado	Descripción
AwaitingAuthorisation	Pendiente de autorización del Usuario Final
AwaitingMultiAuthorisation	Requiere múltiples aprobaciones
Authorised	Aprobado y activo
Rejected	Rechazado por el Usuario Final
Revoked	Revocado post-aprobación
Incomplete	Firmas conjuntas no completadas a tiempo
Expired	Vigencia expirada

 

---

Niveles de Granularidad

Las reglas de Granularidad y Dependencia definen una jerarquía para el acceso a los endpoints de las APIs, determinando la profundidad del acceso a los datos financieros y los permisos previos necesarios.

 

Regla de Granularidad (Niveles de Acceso)

La granularidad divide el nivel de detalle de la información en hasta tres niveles de profundidad:

1. 1er nivel (Primer Nivel): Representa el permiso de acceso general y amplio a una categoría de productos. Se utiliza para consultar la lista de recursos disponibles de un cliente. Por ejemplo, acceder a la lista de todas las cuentas (GET /accounts/v1), tarjetas de crédito (GET /credit-card-accounts/v1/accounts) o préstamos (GET /loans/v1).

2. 2do nivel (Segundo Nivel): Permite enfocarse en un producto específico dentro de esa lista, utilizando su identificador único. Por ejemplo, consultar los datos de solo una cuenta específica a través del endpoint GET /accounts/v1/{accountID}.

3. 3er nivel (Tercer Nivel): Es el grado más profundo de acceso, orientado a consultar detalles operativos específicos y sensibles de ese recurso previamente identificado, como saldos, límites e historial de transacciones. Ejemplos incluyen los endpoints para saldos de cuentas (GET /accounts/v1/{accountID}/balance) o transacciones de inversiones (GET /investments/v1/{investmentID}/transactions).

 

Regla de Dependencia

La dependencia crea un sistema de prerrequisitos en cascada. No se puede conceder un acceso más granular sin que los niveles jerárquicamente superiores también formen parte del alcance autorizado:

1. El acceso al 1er nivel tiene dependencia "N/A" (No aplicable), ya que es la capa base y no depende de ningún otro permiso.

2. El acceso al 2do nivel tiene como dependencia "1er". Esto significa que, para consultar los detalles de un producto específico (como /{accountID}), el sistema exige que la institución también posea el permiso para consultar la lista general de cuentas de ese cliente.

3. El acceso al 3er nivel tiene la dependencia "1er y 2do". Para que la institución pueda leer saldos, transacciones o límites, necesita obligatoriamente las autorizaciones conjuntas para listar las cuentas (1er nivel) y acceder a la cuenta por su ID único (2do nivel).

 

Resumen de Niveles y Dependencias

Nivel	Ejemplo	Dependencia
1er	GET /accounts/v1	N/A
2do	GET /accounts/v1/{accountId}	1er nivel
3er	GET /accounts/v1/{accountId}/balances	1er y 2do

Para obtener más detalles sobre los niveles de acceso y los permisos, consulte la documentación oficial.

---

Grant Management API Endpoints

Endpoints REST para listar, consultar, auditar y revocar grants identificados por grant_id.

Método	Endpoint	Descripción
GET	/grants	Lista grants activos
GET	/grants/{grant_id}	Detalle de un grant
DELETE	/grants/{grant_id}	Revoca un grant
POST	/grants/{grant_id}/revoke	Revoca (alternativa)
GET	/grants/history	Historial de auditoría

---

Webhooks de Consentimiento

 

Eventos soportados

Los eventos publicados hasta ahora son:

• sfa.consent.authorised

• sfa.consent.revoked

• sfa.consent.rejected

 

Formato y seguridad

Los webhooks usan el formato CloudEvents 1.0, con autenticación vía mTLS y protección contra replay mediante los headers X-Idempotency-Key y X-Nonce.

Actualizado en mayo/2026

---