sk donde se espera pk, o viceversa), la API responde 403.
1. Secret key — rail_sk_{live|test}_…
Server-to-server. Es la única credencial que puede leer cuentas y movimientos.
2. Publishable key — rail_pk_{live|test}_…
Browser-safe. La usa el widget para autenticarse al pedir su widget_token.
Exponerla es seguro: el único endpoint que la acepta es
POST /v1/widget_tokens, y el wt_* resultante es single-use y efímero. Un atacante con tu pk_ puede emitir tokens infinitos pero no leer data del banco.3. Widget token — wt_{8hex}_sec_…
Abre el widget de Rail Connect. Single-use.
Para refresh con MFA async, Rail emite automáticamente un token
ri_{intentId}_sec_… dentro del refresh_intent.requires_mfa.widget_token. El widget lo recibe y lo trata igual que un wt_*.
4. Exchange token — et_…
One-shot. El widget lo devuelve al frontend al terminar el connect exitoso. Tu backend lo canjea por el link_id real.
Por qué existe: las credenciales bancarias nunca tocan tu backend. Tu frontend solo ve un
et_ opaco que tu backend canjea por el link_id definitivo.
Modo test vs live
Las keys vienen en dos modos:test: para integración sin tocar bancos reales (sandbox).live: producción. Cada llamada que dispara sync llama al banco real.
sk_test solo se ven con keys _test. No hay cross-talk entre modos. Los responses incluyen "mode": "live" o "mode": "test".
Test mode ya está disponible. Conecta bancos fake con credenciales mágicas (RUT
11.111.111-1 + clave rail-sandbox) y recibe cuentas + movimientos deterministas, sin tocar un banco real. Ver Test mode (Sandbox) para la guía completa y la tabla de escenarios.Manejo de errores de auth
Ver guías → Errores para el shape completo del error envelope.