Claves API

Todo lo que se conecta a MoneyLights desde fuera de la aplicación — un script, una integración, un asistente de IA — se autentica con una clave API. Un tipo de credencial, un lugar para gestionarla, un botón de revocación.

Creando una clave

Ve a Configuración → Claves API como Propietario o Administrador de tu organización. Un Miembro puede editar datos en la aplicación pero no puede emitir una clave: una clave actúa sin supervisión, lo que es un tipo diferente de responsabilidad.

Cuando creas una clave eliges:

Un nombre — nómbrala según el sistema que la usará, no la persona.
Alcances — exactamente lo que la clave puede hacer (ver más abajo).
Una fecha de caducidad — 30, 90, 180 o 365 días. No hay una opción de “nunca expira” a propósito: una credencial de la que nadie piensa de nuevo es una credencial que nadie nota que se ha filtrado.
Una lista de IP permitidas (opcional) — restringe la clave a tu propia infraestructura, así que una clave filtrada es una clave que funciona desde ningún otro lugar.

El secreto (ml_sk_…) se muestra una vez, al crearlo. MoneyLights almacena solo un hash, así que nadie — incluyendo soporte — puede recuperarlo más tarde. Si lo pierdes, rota la clave.

Dale a cada integración su propia clave. Así podrás cortar una sin afectar a las otras, y las cifras de uso te dirán qué sistema está haciendo qué.

Alcances

Los alcances son pares recurso:acción — por ejemplo transactions:read o documents:write. Una clave solo tiene los alcances que le otorgaste, y:

Escribir implica leer, nunca al revés. vendors:write también puede leer proveedores; vendors:read nunca puede escribir.
Los alcances no se pueden editar después de la creación. Necesitar un nuevo alcance significa crear una nueva clave — ampliar una credencial en su lugar sería un cambio que nadie ve.

Lo que una clave puede hacer se recalcula en cada solicitud:

permisos efectivos = los alcances de la clave ∩ lo que su creador puede hacer ahora ∩ tu plan

Así que si la persona que creó una clave es degradada, la clave se restringe en la siguiente llamada. Si dejan la organización, sus claves dejan de funcionar inmediatamente. Emite claves bajo una cuenta que va a permanecer.

Rotación

Rotar emite un nuevo secreto para la misma clave y te permite elegir cuánto tiempo el antiguo sigue funcionando: inmediatamente, 24 horas o 7 días. La ventana existe para que puedas desplegar el nuevo secreto sin tiempo de inactividad. La clave mantiene su nombre, alcances, restricciones de IP y caducidad.

Rota cuando alguien con acceso al secreto se va, cuando puede haber sido expuesto, y en cualquier horario que establezca tu propia política.

Advertencias de caducidad

El creador de la clave es notificado 14, 7 y 1 día antes de que una clave expire, y una vez que ha expirado. Esas notificaciones no se pueden desactivar. No esperes la última: rotar a los 14 días cuesta un despliegue; descubrir una clave expirada a cero cuesta una interrupción.

Almacenando el secreto

Usa variables de entorno o un gestor de secretos — nunca control de versiones, nunca un archivo de configuración que se envíe con tu aplicación.
Nunca pongas la clave en una URL, una línea de registro o un evento de análisis. Las solicitudes que llevan una clave en la cadena de consulta son rechazadas de inmediato.
Nunca uses una clave en código del lado del cliente. Una clave en un navegador o una aplicación móvil ha sido entregada a todos los que la usan.

¿Sospechas una filtración? Revoca primero, investiga después. La revocación está en Configuración → Claves API, tiene efecto inmediato, y siempre está disponible — incluso si tu suscripción está en mora.

Próximos pasos

Con una clave en mano, puedes llamar a la API REST o conectar un asistente de IA a través de MCP — es la misma credencial para ambos.