Las claves de API permiten que scripts, servicios e integraciones externas inicien sesión en Yellow sin que haya una persona en medio. Esta guía es para propietarios de organización que emiten claves a su equipo o a cuentas de servicio. Para claves propiedad del usuario (las tuyas, ligadas a tu cuenta), consulta Tu perfil y configuración.

Qué es una clave de API

Una clave de API es una cadena larga y opaca que autentica una petición como un actor concreto de la plataforma. El actor puede ser:

  • Un usuario — la clave actúa en nombre de ese usuario. Ve lo que ve el usuario, puede hacer lo que el usuario puede hacer.
  • Una cuenta de servicio — un actor no humano creado específicamente para automatización. Tiene su propia pertenencia en una organización y sus propias asignaciones de roles, separadas de cualquier persona real.

Las cuentas de servicio son la forma recomendada para integraciones: cuando el ingeniero que montó la integración se va, la clave sigue funcionando porque no depende de una cuenta personal.

Emitir una clave

Desde la página de la organización → Claves de API → + Nueva clave:

  1. Propietario — el usuario o cuenta de servicio con el que se autentica la clave.
  2. Nombre — lo que quieres recordar ("Webhook de Stripe", "Informe nocturno").
  3. Ámbito — qué tenants y capacidades puede tocar la clave. A menudo más estrecho que los permisos completos del propietario, para que la clave solo haga el trabajo para el que se emitió.
  4. Caducidad (opcional) — una fecha tras la cual la clave deja de funcionar. Recomendado para integraciones de corta duración.
  5. Guarda.

El valor de la clave se muestra una sola vez, al emitirla. Cópialo inmediatamente al gestor de secretos del sistema consumidor. Yellow no guarda el valor en claro — si lo pierdes, debes rotar a una clave nueva.

Capacidades y ámbito

Una clave no puede hacer más de lo que su propietario puede. Si el propietario es una cuenta de servicio con el rol Editor de ventas sobre el schema CRM, la clave solo puede editar datos del CRM. Emitir una clave no eleva permisos — primero concedes capacidades al propietario, luego emites la clave.

Para claves con privilegios mínimos, crea una cuenta de servicio dedicada para cada integración, dale solo los roles que necesita la integración, y luego emite la clave.

Rotar una clave

Cuando rotas una clave, Yellow emite un valor nuevo e invalida el antiguo inmediatamente. Desde la fila de la clave, haz clic en Rotar, copia el nuevo valor, actualiza el sistema consumidor.

Rota de manera proactiva:

  • Cada 90 días para cualquier clave que toque producción, como higiene básica.
  • Inmediatamente si sospechas una fuga (la clave estaba en un commit público, en una pantalla compartida, en un portátil antiguo).
  • Cuando un miembro del equipo que conocía el valor se va.

Revocar una clave

Revocar mata una clave permanentemente. El sistema consumidor empieza a fallar en su próxima petición — no hay periodo de gracia. Usa la revocación para claves de un solo uso que han cumplido su propósito, o para claves comprometidas cuando la rotación no es suficiente.

Auditar el uso de una clave

Cada clave lleva metadatos que puedes inspeccionar:

  • Último uso — la petición con éxito más reciente.
  • Emisor — quién creó la clave.
  • Actor propietario — quién actúa como la clave.

Las claves inactivas mucho tiempo (último uso hace meses, sin propósito aparente) son buenas candidatas a rotación o revocación. Yellow no las elimina automáticamente.

Lista de comprobación de seguridad

  • Emite una clave por integración; nunca compartas una entre consumidores.
  • Usa cuentas de servicio, no usuarios personales, para automatización.
  • Pon caducidad a las claves de corta duración.
  • Guarda las claves solo en un gestor de secretos — nunca en el control de versiones, nunca en documentos compartidos.
  • Revoca las claves de los miembros que se van el mismo día.

Relacionados