Claves API
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 | Organización | |
|---|---|---|
| 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 organización son un recurso a nivel de organización, desvinculado de una sola persona, justo lo que necesitas para credenciales que deben seguir vigentes aunque alguien deje la empresa o cambie de rol.
Crear una clave#
Abre la página de claves de API en Configuración. Las claves personales y de organización están en pestañas separadas; la pestaña Organization requiere el plan Enterprise.
Haz clic en Nueva clave personal, asígnale un nombre (por ejemplo, "MCP local", "clave de staging de Max") y copia la clave cuando aparezca. La clave hereda tu rol actual de RBAC y tus 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 organización y RBAC#
Las claves de organización reflejan el modelo de usuario: un usuario puede tener un rol a nivel de organización (permisos generales mediante Roles y permisos) Y/O permisos por motor por estar agregado a motores específicos. Una clave de organización 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 selecciones durante la creación. Después, puedes actualizar la lista de motores editando 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 organización dependen de la habilitación de RBAC. Si esa habilitación se elimina, todas las claves de organización se desactivan: las solicitudes devuelven 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 cambiar a una clave de 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 organización tienen su propia autoridad. Editar el rol o el alcance surte efecto de inmediato; eliminar la clave la revoca.
- No hay límite en la cantidad de claves por organización.