Rotar o revocar la llave de una API

Cambias la llave de tu API sin volver a configurar nada, o cortas el canal por completo cuando ya no lo quieres.

Antes de empezar#

• Necesitas el permiso de «Integraciones» con alcance de «Toda la empresa» (de fábrica, el Superadministrador y el Administrador) y el plan Empresarial.
• Avisa antes a quien te integra: en cuanto rotes, su sistema deja de consultar hasta que pegue la llave nueva.
• Decide dónde vas a guardar la llave nueva. Igual que la primera, se muestra una sola vez.

Pasos#

1. En el menú, en el grupo «Control», entra a «Integraciones». Si tienes varias sucursales, abre primero el selector de arriba del menú y elige la fila «Todas las sucursales».
2. Lee la columna «Última llamada»: dice cuándo se usó cada llave y desde qué dirección de internet. Con el filtro «Última llamada» dejas ver solo las «Ya usada» o las «Sin usar», que es como se encuentran las llaves olvidadas.
3. Abre la API que quieres cambiar.
4. Para cambiar solo la llave, en el panel «Token» pulsa «Rotar token».
5. En «Confirma que eres tú», escribe tu «Contraseña actual» y pulsa «Confirmar». Si tu cuenta tiene passkey o código de la app, la ventana te deja confirmar con eso.
6. En «Token rotado» pulsa «Copiar» y guarda la llave nueva; con la flecha del mismo botón puedes elegir «Descargar .txt». Después pulsa «Ya las guardé».
7. Pega la llave nueva en tu sistema, solo del lado del servidor. La ficha lo advierte en «Cómo consultar»: «Este token es de servidor: nunca lo pongas en una app web o móvil.»
8. Si lo que quieres es cortar el canal completo, abre la API y, arriba de la ficha, pulsa «Revocar».
9. Lee la advertencia —«El token deja de servir al instante, sus webhooks se apagan y las entregas pendientes se cancelan. No hay vuelta atrás.»— y pulsa «Revocar» para confirmar.

Resultado#

Si rotaste, la llave anterior muere en ese instante y la nueva sirve desde ya. La API queda igual: mismo nombre, lo mismo expuesto y los mismos webhooks; la placa que empieza con pfk_ tampoco cambia, porque no es la llave, sino el identificador con el que reconoces esa conexión y la citas si pides ayuda.

Si revocaste, sale el aviso «API revocada» y vuelves a la lista, donde esa API ya no aparece. Quien abra la liga vieja lee «Esta integración ya no existe».

Preguntas frecuentes#

¿Tengo que volver a marcar qué expone o a configurar mis webhooks al rotar? No. Rotar cambia la llave y nada más: los recursos, los campos y los webhooks siguen tal cual, y sus secretos de firma no se tocan.

¿Cómo me doy cuenta de que alguien más usa mi llave? Por la columna «Última llamada»: si marca una hora en la que tu sistema no consulta, o una dirección de internet que no es la suya, rótala. Además, cuando la llave se usa desde una dirección distinta a la anterior, te llega un correo a ti y a quien más administre las integraciones.

¿Se puede deshacer una revocación? No. Hay que crear otra API, volver a marcar qué expone y entregar la llave nueva a quien te integra.

Se fue quien creó la llave. ¿Se cae mi conexión? No. La llave es de la empresa, no de la persona: sigue trabajando aunque su cuenta se dé de baja.