Las claves API autentican las solicitudes a la API de localización y al servidor MCP. Lingo.dev ofrece dos tipos: elige el que mejor encaje con quién, o qué, hace la llamada a la API.
Dos tipos de claves#
| Personal | Servicio | |
|---|---|---|
| Propietario | El usuario que la creó | Ninguno: está pensada para automatizaciones |
| Autorización | Hereda el rol RBAC del creador y los permisos por motor | Tiene su propio rol y/o alcance por motor |
| Si el propietario pierde el acceso | La clave también lo pierde | No se ve afectada; depende del rol o alcance propios de la clave |
| Plan | Cualquier plan | Enterprise (requiere la prestación RBAC) |
| Uso habitual | Desarrollo local, MCP y scripts puntuales | Pipelines CI/CD e integraciones en producción |
Las claves personales son la opción predeterminada. Las claves de servicio son un recurso a nivel de organización, desvinculado de cualquier persona concreta, justo lo que necesitas para credenciales que deben seguir funcionando aunque alguien deje la empresa o cambie de rol.
Crear una clave#
Abre la página Claves API en el panel. Personal y Servicio están en pestañas independientes; la pestaña Servicio solo aparece cuando tu organización tiene el plan Enterprise.
Haz clic en Crear clave API, asígnale un nombre (por ejemplo, "MCP local" o "clave de staging de Max") y copia la clave desde el cuadro de diálogo de confirmación. La clave hereda tu rol RBAC actual y los permisos por motor.
Visibilidad de la clave
La clave API completa solo se muestra una vez, al crearla. Cópiala y guárdala en un lugar seguro: no podrás recuperarla después de cerrar el cuadro de diálogo.
Claves de servicio y RBAC#
Las claves de servicio reflejan el modelo de usuario: un usuario puede tener un rol a nivel de organización (permisos globales mediante Roles & Permissions) Y/O permisos por motor por haber sido añadido a motores concretos. Una clave de servicio funciona igual:
- Solo rol: los permisos del rol se aplican a toda la organización. Si incluye
engine:access, la clave puede acceder a todos los motores de la organización. - Sin rol + alcance por motor: la clave queda restringida a los motores que marques durante la creación. Más adelante puedes actualizar la lista desde el botón Motores x/y junto a la clave.
- Rol + alcance por motor: ambas autoridades son acumulativas. El alcance global del rol prevalece si concede
engine:access; en caso contrario, se consulta la lista por motor. - Ninguno: la clave autentica, pero no puede acceder a ningún motor. Puede servir como marcador de posición mientras configuras el alcance, pero no tiene sentido en producción.
Las protecciones antiescalado se aplican tanto al crear como al editar:
- El rol elegido debe pertenecer a la misma organización.
- El conjunto de permisos del rol debe ser un subconjunto de
engine:access; los roles más amplios, por ejemplo uno que incluyaorg:manage_team, se rechazan. - Solo puedes añadir un motor al alcance de la clave si tú ya tienes acceso a ese motor.
Si tu plan Enterprise vence
Las claves de servicio forman parte de la prestación RBAC. Si esa prestación se elimina, todas las claves de servicio de la organización quedan desactivadas: las solicitudes devolverán un 403 y un mensaje que apunta al plan, no al alcance por motor. Las claves personales no se ven afectadas. Puedes restaurar el plan Enterprise o rotar a una clave API personal.
Usar una clave#
Incluye la clave API en la cabecera X-API-Key en cada solicitud; el formato es el mismo para ambos tipos:
curl -X POST https://api.lingo.dev/process/localize \
-H "X-API-Key: your_api_key" \
-H "Content-Type: application/json" \
-d '{"engineId": "eng_abc123", "sourceLocale": "en", "targetLocale": "de", "data": {"greeting": "Hello"}}'La misma clave sirve tanto para la API de localización como para el servidor MCP.
Seguridad#
- Las claves se almacenan como hashes: Lingo.dev no puede recuperar una clave después de crearla. Para rotarla, elimínala y vuelve a crearla.
- Las claves personales siguen en tiempo real los permisos de su creador. Si el rol del creador se degrada o se revoca un permiso por motor, la clave perderá ese mismo acceso en la siguiente llamada.
- Una clave personal cuyo creador haya sido eliminado de la organización seguirá funcionando solo mientras RBAC esté desactivado (comportamiento heredado). En cuanto RBAC se active, se denegará; rótala antes de que quede huérfana.
- Las claves de servicio tienen su propia autoridad. Editar el rol o el alcance desde la pestaña Servicio surte efecto de inmediato; eliminar la clave la revoca.
- No hay límite en el número de claves por organización.
