Saltar al contenido

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

PrefijoTipoDónde se usaQué permite
banky_sk_test_Secret · testTu servidorToda la API v1 y MCP, solo con datos de test.
banky_sk_live_Secret · liveTu servidorToda la API v1 y MCP, con datos reales.
banky_pk_test_Publishable · testNavegador o appSolo POST /v1/link_tokens y GET /v1/institutions.
banky_pk_live_Publishable · liveNavegador o appSolo 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

HTTPcodeCausa
401missing_api_keyNo enviaste el encabezado Authorization o no usa el formato «Bearer <llave>».
401invalid_api_keyLa llave no existe, fue revocada o no tiene el formato de una llave.
403secret_key_requiredUsaste una llave publishable en un endpoint que exige una llave secret.
429rate_limitedSuperaste 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 Authorization en 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.