Claves de API

Elige entre permisos personales o de servicio, guarda el secreto al crearlo y sustituye las credenciales sin perder de vista los clientes que las utilizan.

Una clave de API permite que un cliente actúe con unos permisos definidos. Una clave personal está vinculada a la pertenencia y los permisos de una persona en la organización. Una clave de servicio pertenece a la organización, de modo que la automatización puede seguir funcionando aunque alguien deje el equipo. Con RBAC, una clave de servicio también puede tener su propio rol y ámbito de recursos.

El secreto se muestra al crear la clave y no se puede recuperar consultando su registro más adelante. Guárdalo inmediatamente en un gestor de secretos o en el almacén de credenciales que admita el cliente. No lo incluyas en archivos de código fuente, configuraciones guardadas en el repositorio, capturas de pantalla ni mensajes al equipo de soporte.

Usa una clave personal para trabajar a título individual #

En Configuración → Claves de API → Personal de la organización seleccionada, crea una clave personal y asígnale un nombre. Cualquier miembro puede crear una para su propio uso. Sus permisos dependen de la pertenencia actual a la organización y de los permisos efectivos de quien la creó; no se le puede asignar un rol independiente ni un ámbito por motor de localización, como sí ocurre con una clave de servicio.

Esta opción resulta útil para un cliente local que actúa en nombre de quien lo utiliza. Si esa persona deja la organización o pierde permisos, el acceso de la clave también cambia. Usa una clave de servicio cuando la automatización de la organización no deba depender de que esa persona conserve su acceso.

Crea una clave de servicio #

En Configuración → Claves de API → Organización de la organización seleccionada, selecciona Nueva clave de organización. Las claves de servicio están disponibles en todos los planes. Para crear una, se requiere org:manage_api_keys.

Sin RBAC, no se puede limitar el alcance de una clave de servicio: permite leer y traducir con todos los motores de localización de la organización. El formulario de creación muestra una nota en lugar de los campos de rol y motor.

Este acceso básico no permite usar la clave para editar o eliminar motores de localización, revisar traducciones ni administrar la organización.

Con RBAC, puedes asignar a la clave un rol, un ámbito de motores de localización o ambos, y modificarlos más adelante. El cliente debe poder delegar el rol seleccionado y traducir con todos los motores de localización incluidos en el ámbito. El permiso de lectura por sí solo no basta para conceder permisos de traducción sobre ese ámbito.

Los únicos roles de servicio permitidos son engine:read y engine:translate. El rol debe pertenecer a la organización y no puede incluir permisos administrativos más amplios. Una clave de servicio también puede no tener ningún rol y basarse en permisos concedidos expresamente sobre los recursos.

Configura por separado el ámbito de los motores de localización y el de los recursos de contenido y, después, vuelve a consultar cada campo guardado. Una actualización de permisos puede fallar mientras otra se completa correctamente. Los permisos del rol y los concedidos expresamente se suman; un ámbito limitado no anula un acceso más amplio derivado del rol. Con RBAC, crear una clave no basta para darle permisos efectivos de traducción si no tiene un rol adecuado ni permisos sobre los recursos.

Usa la interfaz de gestión de claves para crearlas y modificar su ámbito. Al automatizar este ciclo de vida, comprueba que el cliente elegido ofrece la operación de gestión necesaria, en lugar de dar por hecho que todos los clientes la ofrecen.

Antes de eliminar RBAC

Si se elimina RBAC, las claves de servicio ordinarias vuelven a tener acceso de lectura y traducción en toda la organización. Las restricciones de rol y motor guardadas dejan de limitar ese acceso. Revoca o rota las claves antes de eliminar RBAC si necesitas mantener esas restricciones. Las credenciales para fines específicos, como las claves SCIM, tienen requisitos de acceso independientes.

Rota o revoca una credencial #

La rotación consiste en una sustitución manual:

  1. Crea una clave de sustitución del tipo previsto y con los permisos mínimos necesarios.
  2. Guarda su secreto en el mecanismo de gestión de secretos del cliente.
  3. Actualiza los clientes que dependen de ella y comprueba una operación sencilla de las previstas a través de la interfaz que admitan.
  4. Revoca la clave antigua después de la comprobación. Si la exposición del secreto exige medidas de contención inmediatas, revócala primero y ten en cuenta la interrupción.
  5. Revisa los registros actuales de las claves y los fallos de los clientes para detectar dependencias que se hayan pasado por alto.

Cualquier miembro de la organización con acceso al registro de la clave puede revocar una clave ordinaria, ya sea personal o de servicio. Este permiso de revocación es más amplio que el permiso para crear una clave de servicio o modificar su ámbito. Para revocar una clave SCIM, se requiere el rol de propietario de la organización. Al hablar de su eliminación, utiliza el identificador de la clave, no su secreto.

La revocación no elimina las copias almacenadas en otros lugares ni revoca las sesiones del navegador. Este ciclo de vida no implica que exista un calendario automático de rotación o caducidad.

Configura el cliente que realiza las llamadas #

Las solicitudes REST usan la cabecera X-API-Key de la API seleccionada. Un código 401 apunta a un problema de autenticación; un código 403 indica que se han denegado los permisos. Comprueba la credencial en el primer caso y los permisos y el ámbito de recursos de la identidad en el segundo. No incluyas credenciales en URL improvisadas.

Consulta Autenticación de la API, Autenticación de la CLI o el contrato de conexión MCP para conocer cómo gestiona el cliente la transmisión y el almacenamiento. El motor de localización seleccionado debe estar siempre dentro del ámbito de permisos de ese cliente.