La clave solo se ve una vez: cómo debe tu equipo guardar, rotar y revocar las claves de API
Cuando emites una clave de API en el panel de SimAggregator, la cadena de la clave aparece en pantalla exactamente una vez. Si cierras la ventana sin copiarla, nadie puede volver a ver esa cadena, tampoco nosotros: la plataforma guarda solo una huella de la clave, no la cadena en sí. Una clave perdida no se puede recuperar, solo sustituir: emites una nueva y revocas la antigua. Por eso conviene organizar la rotación y la revocación de antemano, antes de que se filtre nada.
Una clave por entorno y por servicio
Una clave actúa en nombre de tu cuenta y gasta su saldo: quien tenga la cadena puede comprar números a tu costa. Con una única clave compartida «para todo», una filtración te deja adivinando dónde ocurrió, y revocar la clave rompe todas las integraciones a la vez.
En el panel puedes emitir varias claves y dar un nombre a cada una. Recomendamos un esquema «entorno + servicio»: prod-bot, staging-bot, ci-tests. El nombre te dice enseguida qué dejará de funcionar cuando revoques la clave y a quién preguntar por una actividad extraña. El límite de la API, 600 peticiones por minuto, se aplica por clave, así que una ejecución de pruebas en CI no le quita peticiones a tu servicio de producción.
CI tiene una trampa: un getNumber llamado desde ahí compra números reales con el mismo saldo. No puedes cancelar un pedido así hasta que haya pasado al menos un minuto. Los pedidos cancelados sin código bajan tu proporción de pedidos que recibieron código en 7 días, y la reputación de tu cuenta fija el límite de pedidos simultáneos, que CI y el bot de producción comparten. Para las pruebas de humo suelen bastar getBalance y getPrices.
Dónde guardar la cadena de la clave
Justo después de emitir una clave, ponla en un gestor de secretos o en variables protegidas de CI que se enmascaren en los logs. No la pongas en el repositorio, ni en un archivo .env incluido en un commit «solo por ahora», ni en un chat del equipo, ni en un ticket. El desarrollador que construye la integración normalmente no necesita la cadena de la clave de producción: el servicio la toma del almacén de secretos al arrancar.
La API es compatible con sms-activate y solo acepta peticiones GET, así que la clave viaja en la cadena de consulta. Asegúrate de que tu cliente HTTP, tus proxies y tus logs de acceso no registren la URL completa de la petición. Los logs se guardan durante mucho tiempo y mucha gente puede leerlos, así que trata como filtrada cualquier clave que acabe en un log.
Rotación: primero la clave nueva, después se revoca la antigua
La rotación se reduce a dos acciones en el panel: emitir una clave nueva y revocar la antigua. En ese orden, la clave antigua sigue funcionando hasta que el servicio pasa a la nueva, y ninguna petición falla.
- Emite una clave nueva con el mismo propósito en el nombre, por ejemplo
prod-bot-2. - Guárdala en tu gestor de secretos en lugar del valor antiguo.
- Reinicia el servicio para que tome la clave nueva.
- Comprueba el panel: la clave nueva ya muestra la fecha de su última solicitud, y la fecha de la antigua ha dejado de cambiar.
- Revoca la clave antigua.
Rota fuera de tu calendario habitual si:
- alguien que vio la clave ha dejado el equipo;
- la clave acabó en un log, una captura de pantalla, un chat o un repositorio;
- te pasaste a otro hosting o a otro CI.
Vincula la rotación programada al mismo calendario que usas para tus otros secretos.
Auditoría por fecha de la última solicitud
Abre la lista de claves antes de un lanzamiento o cada vez que revises los accesos. Una clave que no se usa desde hace mucho probablemente sea un resto de un proyecto cerrado, así que revócala. Si la clave staging-bot se está usando pero el propio bot de staging se apagó hace una semana, revoca la clave enseguida y averigua de dónde vienen las peticiones. También es más fácil revocar una clave con un nombre poco claro que adivinar de quién es. Si alguien la necesita, el dueño lo notará por su propio servicio y emitirá una clave nueva con un nombre claro.
Protege la cuenta en sí
Una clave de API es tan segura como tu cuenta: cualquiera que inicie sesión en el panel puede emitir una clave nueva para sí mismo y gastar tu saldo. Por eso, activa la autenticación de dos factores: configuras un código TOTP de una app de autenticación en la página de inicio de sesión, y ahí mismo cambias también la contraseña. Si sospechas que otra persona ha entrado en tu cuenta, cierra la sesión en otros dispositivos, cambia la contraseña y rota todas tus claves. Sigue los mismos pasos cuando deje el equipo alguien que tenía acceso al panel.
Para empezar, activa el 2FA en la página de inicio de sesión. Después emite en el panel claves con nombre aparte para prod, staging y CI, ponlas en tu gestor de secretos y revoca tu clave compartida, si la tenías.