Claves de API

Elige entre permisos personales o de servicio, guarda el secreto al crearlo y reemplaza las credenciales sin perder de vista qué clientes las usan.

Una clave de API permite que un cliente actúe con permisos definidos. Una clave personal está vinculada a la membresía y los permisos de una persona. Una clave de servicio de la organización pertenece a la organización, de modo que la automatización no dependa de la permanencia de alguien del equipo. Con RBAC, una clave de servicio también puede tener su propio rol y alcance de recursos.

El secreto se muestra al crear la clave y no se puede recuperar después desde los registros de claves. Guárdalo de inmediato 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 de soporte.

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

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 uso propio. Sus permisos dependen de la membresía actual y los permisos efectivos de quien la creó; a diferencia de una clave de servicio, no se le puede asignar un rol independiente ni limitar su alcance por motor de localización.

Esto es útil para un cliente local que actúa en nombre de quien lo opera. Si el miembro 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: tiene acceso de lectura y traducción 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 que la clave edite o elimine motores de localización, revise traducciones ni administre la organización.

Con RBAC, puedes asignar a la clave un rol, un alcance de motores de localización o ambos, y modificarlos después. El cliente debe poder delegar el rol seleccionado y traducir con cada motor de localización incluido en el alcance. El permiso de lectura por sí solo no basta para otorgar un alcance de traducción.

Los roles permitidos para las claves de servicio 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 quedar sin rol y depender de permisos sobre recursos otorgados expresamente.

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

Usa la interfaz de administración de claves para crearlas y editar su alcance. Si automatizas este ciclo de vida, verifica que el cliente elegido ofrezca la operación de administración necesaria, en lugar de dar por hecho que todos los clientes la ofrecen.

Antes de quitar RBAC

Si se quita RBAC, las claves de servicio comunes 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 quitar 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 un reemplazo manual:

  1. Crea una clave de reemplazo 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 verifica una operación prevista de pequeña escala mediante la interfaz que admita cada uno.
  4. Revoca la clave anterior después de verificarla. Si la exposición de la clave exige contener el riesgo de inmediato, revócala primero y ten en cuenta la interrupción.
  5. Revisa los registros actuales de claves y las fallas 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 personal o de servicio común. Este permiso de revocación es más amplio que el permiso para crear una clave de servicio o editar su alcance. Solo el Propietario de la organización puede revocar claves SCIM. Al hablar de la eliminación de una clave, usa su identificador, no su secreto.

La revocación no borra las copias almacenadas en otros lugares ni revoca las sesiones del navegador. Este ciclo de vida no implica una programación automática de rotación ni de vencimiento.

Configura el cliente que usará la clave #

Las solicitudes REST usan el encabezado X-API-Key de la API seleccionada. Un código 401 indica un problema de autenticación; un 403 indica que la autorización fue denegada. En el primer caso, verifica la credencial; en el segundo, los permisos y el alcance de recursos de la entidad que realiza la solicitud. No incluyas credenciales en URL improvisadas.

Consulta Autenticación de API, Autenticación de CLI o el Contrato de conexión MCP para conocer cómo el cliente transmite y almacena las credenciales. El motor de localización seleccionado debe mantenerse dentro del alcance de los permisos de ese cliente.