Claves API
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 | Organización | |
|---|---|---|
| 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 organización son un recurso a nivel de organización desvinculado de una persona concreta, justo lo que necesitas para credenciales que deben seguir funcionando cuando alguien deja la empresa o cambia de rol.
Crear una clave#
Abre la página de claves 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, ponle un nombre (por ejemplo, "MCP local" o "clave de staging de Max") y copia la clave cuando aparezca. La clave hereda tu rol actual de RBAC 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 organización y RBAC#
Las claves de organización siguen el mismo modelo que los usuarios: un usuario puede tener un rol a nivel de organización (permisos generales mediante Roles y permisos) Y/O permisos por motor al añadirse a motores concretos. 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 de motor: la clave queda restringida a los motores que selecciones durante la creación. Puedes actualizar la lista de motores más adelante editando 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 organización forman parte del derecho RBAC. Si se elimina ese derecho, todas las claves de organización se desactivan: las solicitudes devuelven un 403 y un mensaje que apunta al plan, no al alcance del motor. Las claves personales no se ven afectadas. Restaura el plan Enterprise o cambia 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 organización tienen su propia autoridad. Editar el rol o el alcance surte efecto de inmediato; eliminar la clave revoca su acceso.
- No hay límite en el número de claves por organización.