Primeros pasos
Autenticación
La API se autentica con llaves que creas en el panel. El prefijo de cada llave indica su tipo y su modo, así que con solo leerla sabes qué puede hacer.
Tipos de llave
| Prefijo | Tipo | Dónde se usa | Qué permite |
|---|---|---|---|
banky_sk_test_ | Secret · test | Tu servidor | Toda la API v1 y MCP, solo con datos de test. |
banky_sk_live_ | Secret · live | Tu servidor | Toda la API v1 y MCP, con datos reales. |
banky_pk_test_ | Publishable · test | Navegador o app | Solo POST /v1/link_tokens y GET /v1/institutions. |
banky_pk_live_ | Publishable · live | Navegador o app | Solo POST /v1/link_tokens y GET /v1/institutions. |
Las llaves tienen el prefijo seguido de 40 caracteres alfanuméricos. Se muestran completas una sola vez, al crearlas: en nuestra base guardamos solo su huella SHA-256 y un prefijo visible (por ejemplo banky_sk_live_44a…) para que las reconozcas en el panel. Si pierdes una llave, revócala y crea otra.
Enviar la llave
Envía la llave en el encabezado Authorization con el esquema Bearer. Todas las solicitudes deben ir por HTTPS.
curl "https://api.banky.cl/v1/links" \
-H "Authorization: Bearer $BANKY_SECRET_KEY"Para comprobar que tu llave funciona sin tocar datos, puedes llamar a GET /v1/institutions: responde con la lista de bancos del modo de la llave.
Live y test
Live y test son mundos separados dentro de tu organización. Una llave test solo ve conexiones, cuentas, movimientos y webhooks test, y una llave live solo ve los live. El modo de cada objeto viene en su campo mode.
- En test, el widget solo permite conectar el Banco de Prueba; los bancos reales aparecen como próximamente.
- En live, el Banco de Prueba no aparece.
- Un id de un modo responde 404 si lo consultas con una llave del otro modo.
Errores de autenticación
| HTTP | code | Causa |
|---|---|---|
| 401 | missing_api_key | No enviaste el encabezado Authorization o no usa el formato «Bearer <llave>». |
| 401 | invalid_api_key | La llave no existe, fue revocada o no tiene el formato de una llave. |
| 403 | secret_key_required | Usaste una llave publishable en un endpoint que exige una llave secret. |
| 429 | rate_limited | Superaste el límite de solicitudes. Ver Límites de uso. |
Respuesta
401{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "La llave de API no es válida o fue revocada."
}
}Buenas prácticas
- Guarda la llave secret en una variable de entorno o en un gestor de secretos. Nunca en el código, en el repositorio ni en el frontend.
- Usa llaves distintas por entorno (desarrollo, staging, producción) y por servicio, con nombres que las identifiquen.
- Revisa en el panel la fecha de último uso de cada llave y revoca las que no uses. La revocación es inmediata y no se puede deshacer.
- Para cambiar una llave sin cortes: crea la nueva, despliégala, verifica que se esté usando y recién entonces revoca la anterior.
- No registres el encabezado
Authorizationen tus logs. Si una llave se filtra, revócala de inmediato.
Ejemplo de llave test con formato válido (no funciona): banky_sk_test_4eC39HqLyjWDarjtT1zdp7dcVw0kX8sQm2RbNfYu.