Introducción
Bridge utiliza dos mecanismos de autenticación que trabajan en conjunto para proteger los datos financieros de tus usuarios. Esta arquitectura de doble autenticación garantiza que solo tu aplicación pueda acceder a los datos, y que cada solicitud esté limitada únicamente a los recursos autorizados.
Clave de API (API Key)
La Clave de API identifica tu aplicación ante Bridge. Es una credencial secreta que demuestra que las solicitudes provienen de tu servidor autorizado.
Cómo obtenerla
- Accede al Dashboard de Bridge
- Selecciona tu organización y aplicación
- Ve a la sección Llaves de acceso en el menú lateral
- Haz clic en + Nueva llave para crear una nueva clave
Cada aplicación pertenece a un entorno específico (Sandbox o Producción). Para probar en Sandbox, crea una aplicación de prueba; para producción, usa una aplicación de producción.
Cómo usarla
Incluye tu Clave de API en el header Authorization de cada solicitud:
curl https://api.bridge.com.do/connections/con_xxxx \
-H "Authorization: Bearer <tu_clave_de_api>"
Alcance
La Clave de API te da acceso a nivel de aplicación. Con ella puedes realizar operaciones administrativas como consultar o revocar conexiones específicas por su ID, sin necesidad de credenciales adicionales.
Token de Acceso Limitado (Scoped Token)
El Token de Acceso Limitado es una credencial que restringe el acceso a un subconjunto específico de recursos. A diferencia de la Clave de API que identifica tu aplicación, este token determina a qué datos de usuario puedes acceder.
Por qué existe
Los datos financieros sensibles (números de cuenta, balances, transacciones) están encriptados en Bridge. La información de cada usuario está encriptada de forma independiente, y el Token de Acceso Limitado contiene la llave criptográfica necesaria para descifrar únicamente los datos de ese usuario.
Esta arquitectura garantiza que:
- Bridge no puede acceder a los datos sin tu token
- Si pierdes el token, los datos permanecen inaccesibles, protegiendo ante posibles brechas de seguridad
- Cada token está matemáticamente vinculado a un usuario específico
Es importante notar que el Token de Acceso Limitado por sí solo no es suficiente para acceder a la API. Siempre debe estar acompañado de una Clave de API válida de la misma aplicación. Esta combinación garantiza que solo tu servidor autorizado puede descifrar los datos de tus usuarios.
Alcance del token
El alcance del token depende de cómo configuraste Bridge Connect:
Por defecto (sin externalUserId): El token da acceso únicamente a la conexión creada en esa sesión. Cada nueva conexión genera un token independiente.
Con externalUserId: El token da acceso a todas las conexiones del usuario identificado. Solo recibes el token en la primera conexión del usuario; conexiones subsecuentes usan el mismo token.
Para verificar a qué conexiones tiene acceso un token, consulta el endpoint de listar conexiones:
curl https://api.bridge.com.do/connections \
-H "Authorization: Bearer <tu_clave_de_api>" \
-H "X-Scoped-Token: <token_de_acceso>"
Cómo obtenerlo
El token se retorna en el evento onSuccess de Bridge Connect cuando el usuario completa la vinculación de su cuenta:
BridgeConnect.init({
applicationId: "app_xxx",
onSuccess: function ({ connectionId, scopedToken }) {
// scopedToken contiene el Token de Acceso Limitado
// Guárdalo de forma segura en tu backend
},
});
El token solo se retorna una vez. Si lo pierdes, no hay forma de recuperarlo y
el usuario deberá reconectar su cuenta.
Cómo usarlo
Incluye el token en el header X-Scoped-Token:
curl https://api.bridge.com.do/accounts/acc_xxx \
-H "Authorization: Bearer <tu_clave_de_api>" \
-H "X-Scoped-Token: <token_de_acceso>"
Cuándo usar cada credencial
La regla general es simple: las operaciones que acceden a datos sensibles del usuario requieren ambas credenciales, mientras que las operaciones administrativas solo requieren la Clave de API.
| Operación | Clave de API | Token de Acceso Limitado |
|---|
| Obtener una conexión por ID | ✓ | — |
| Revocar una conexión | ✓ | — |
| Listar conexiones del token | ✓ | ✓ |
| Listar cuentas | ✓ | ✓ |
| Obtener detalles de cuenta | ✓ | ✓ |
| Listar transacciones | ✓ | ✓ |
| Obtener una transacción | ✓ | ✓ |
Ejemplos de uso
Solo Clave de API — Revocar una conexión cuando el usuario lo solicita:
curl -X DELETE https://api.bridge.com.do/connections/con_xxx \
-H "Authorization: Bearer <tu_clave_de_api>"
curl https://api.bridge.com.do/accounts/acc_xxx \
-H "Authorization: Bearer <tu_clave_de_api>" \
-H "X-Scoped-Token: <token_de_acceso>"
Seguridad
Nunca expongas tus credenciales en código del lado del cliente. Todas las
llamadas a la API de Bridge deben realizarse desde tu servidor backend.
Mejores prácticas
-
Almacena las credenciales de forma segura — Usa variables de entorno o un gestor de secretos. Nunca las incluyas directamente en el código.
-
Asocia el token al usuario — Guarda el Token de Acceso Limitado en tu base de datos, vinculado al usuario correspondiente, para poder realizar consultas futuras.
-
No registres credenciales en logs — Evita incluir tokens o claves en mensajes de log o reportes de error.
-
Usa siempre HTTPS — Todas las comunicaciones con la API de Bridge deben ser a través de conexiones seguras.
-
Responde ante compromisos — Si sospechas que una credencial fue expuesta, genera una nueva Clave de API desde el dashboard.
Errores comunes
| Código | Significado |
|---|
401 Unauthorized | Clave de API inválida o faltante |
403 Forbidden | Token de Acceso Limitado inválido o sin permisos para el recurso solicitado |
Próximos pasos
