Las claves API autentican solicitudes a la API de localización y al servidor MCP. Lingo.dev admite dos tipos: elige el que mejor se ajuste a quién o qué está llamando a la API.
Dos tipos de claves#
| Personal | Servicio | |
|---|---|---|
| Propietario | El usuario que la creó | Ninguno: está pensada para automatización |
| Autorización | Hereda el rol de RBAC del creador + permisos por motor | Tiene su propio rol y/o alcance por motor |
| Si el propietario pierde acceso | La clave también pierde acceso | No se ve afectada; depende del rol o alcance de la propia clave |
| Plan | Cualquier plan | Enterprise (requiere la habilitación de RBAC) |
| Uso habitual | Desarrollo local, MCP, scripts ad hoc | Pipelines de CI/CD, integraciones de 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 en particular, justo lo que necesitas para credenciales que deben seguir funcionando aunque cambie el personal o se modifiquen roles.
Crear una clave#
Abre la página de Claves API en el panel. Personal y Servicio están en pestañas separadas; la pestaña Servicio solo aparece cuando tu organización tiene el plan Enterprise.
Haz clic en Create API key, asígnale un nombre (por ejemplo, "Local MCP", "clave de staging de Max") y copia la clave desde el cuadro de confirmación. La clave hereda tu rol actual de RBAC y los permisos por motor.
Visibilidad de la clave
La clave API completa se muestra una sola vez al momento de crearla. Cópiala y guárdala de forma segura; no podrás recuperarla después de cerrar el cuadro.
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 generales mediante Roles & Permissions) Y/O permisos por motor por haber sido agregado a motores específicos. 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. Después puedes actualizar la lista desde el botón Engines x/y junto a la clave.
- Rol + alcance por motor — ambas autoridades son acumulativas. Los permisos generales del rol prevalecen si otorgan
engine:access; de lo contrario, se consulta la lista por motor. - Ninguno — la clave autentica, pero no puede acceder a ningún motor. Es útil como marcador provisional mientras configuras el alcance, pero no tiene sentido en producción.
Las protecciones anti-escalación 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; se rechazan los roles más amplios (por ejemplo, uno que incluyaorg:manage_team). - Solo puedes agregar 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 habilitación de RBAC. Si se elimina esa habilitación, todas las claves de servicio de la organización quedan desactivadas: las solicitudes devuelven un 403 y un mensaje que apunta al plan, no al alcance por motor. Las claves personales no se ven afectadas. Restaura el plan Enterprise o cambia a una clave API personal.
Usar una clave#
Envía la clave API en el encabezado 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 funciona 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 los permisos de su creador en tiempo real. Si se reduce el rol del creador o se revoca un permiso por motor, la clave pierde ese mismo acceso en la siguiente llamada.
- Una clave personal cuyo creador fue eliminado de la organización sigue funcionando solo mientras RBAC esté desactivado (comportamiento heredado). En cuanto RBAC se activa, se deniega: 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 la cantidad de claves por organización.
