Clés d'API
Una clave de API es lo que te deja publicar sin sesión de navegador: desde un script, desde tu Makefile o desde el CI. Detrás está la misma máquina que el panel, con una clave en lugar de una cookie.
Se crean en claves de API.
Crear una
Rellena los cuatro campos y créala. Después, copia el secreto ahí mismo: sale una sola vez, en esa pantalla, y no hay segunda oportunidad ni enlace para volver a verlo.
| Campo | Qué es | Consejo |
|---|---|---|
| Etiqueta | Nombre para reconocerla en la lista (2–60 caracteres). | Pon dónde vive, no qué hace: CI de GitHub — Clipio. El día que veas un uso raro querrás saber qué máquina la tiene. |
| Ámbitos | Qué puede hacer. | Para un CI, sólo publish. |
| App | La ata a UNA aplicación. | Átala siempre. |
| Caducidad | 30, 90 o 365 días; vacío, no caduca. | Pon una. 365 está bien para un CI. |
Máximo 20 claves vivas por cuenta. Ni las revocadas ni las caducadas ocupan sitio: si una clave ya no sirve, tampoco te estorba.
Los dos ámbitos
| Ámbito | Permite |
|---|---|
publish | Crear fichas, crear versiones, subir artefactos y publicar. Escribe. |
read | Consultar tus fichas y el estado de tus versiones. No escribe nada. |
No hace falta marcar los dos. Una clave con publish ya puede leer lo suyo: consultar el estado de la versión que acabas de subir es parte de publicar. Si se exigieran las dos casillas para eso, todo el mundo crearía todas las claves con publish + read y la distinción no distinguiría nada.
Al revés no aplica: read no escribe nunca.
Atarla a una sola aplicación
Porque el radio de la explosión importa. Una clave sin atar puede publicar en todas tus fichas: si se escapa la del CI de un proyecto de fin de semana, quien la tenga puede subir un binario a tu aplicación principal.
Atada a una app, ese mismo escape sólo alcanza a esa app. El servidor lo comprueba en cada petición, y el 403 te dice cuál de las dos cosas ha fallado:
Esta clave de API está atada a otra aplicación: no puede tocar esta.
Esta clave de API no tiene el ámbito «publish».Dos efectos secundarios del atado, para que no te pillen por sorpresa:
- Una clave atada no puede crear fichas nuevas. La primera ficha se crea desde el panel —que es donde eliges categoría, capturas e icono mirándolo— o con una clave sin atar.
- Pedir la lista de tus fichas con una clave atada devuelve sólo esa app. El CI de una aplicación no tiene por qué enterarse de qué más hay en tu cuenta.
Una clave por repositorio. Si compartes una entre dos CI, el día que haya que revocarla tumbas los dos.
Ponerle caducidad
Una clave que no caduca es una clave que nunca vas a rotar. Con caducidad, un día el CI falla con un 401 claro, entras al panel, creas otra y sigues. Sin ella, la clave que creaste hace tres años sigue viva en un repositorio que ya no miras.
Seguridad
Se enseña una vez, y punto
El servidor guarda el SHA-256 de la clave, nunca la clave. Ni nosotros podemos leerla. Si la pierdes no hay recuperación: se revoca y se crea otra.
Lo que sí se guarda es un prefijo visible (flg_AbCdEf…) para que reconozcas cuál es cuál en la lista.
La pantalla que enseña el secreto se sirve con Cache-Control: no-store y no pasa por ninguna redirección: el secreto no queda en el historial del navegador, ni en el registro de accesos del proxy, ni en el Referer de ningún recurso de la página.
Dónde se guarda: como secreto del repositorio, nunca en el código
En GitHub: Settings → Secrets and variables → Actions → New repository secret, con nombre FULGEON_TOKEN. Se usa después como ${{ secrets.FULGEON_TOKEN }} y GitHub la enmascara en los registros.
Lo que no vale, aunque parezca inofensivo:
- Un
.envque acaba subido al repositorio «temporalmente». - Un
echo $FULGEON_TOKENpara depurar. El registro del CI de un repositorio público lo lee cualquiera, y se queda ahí para siempre. - Pasarla como argumento de línea de comandos: aparece en la lista de procesos de la máquina y en tu historial del shell. Usa la variable de entorno.
En el CLI, FULGEON_TOKEN gana sobre la clave guardada en disco. Es a propósito: así un ~/.config olvidado en un runner compartido no puede publicar en tu nombre.
Por qué el prefijo flg_
Que la clave empiece por flg_ y tenga una forma reconocible no es cosmético: es lo que permite que los escáneres de secretos —el de GitHub y los que corren en los CI— la detecten cuando alguien la sube por error a un repositorio público. Un token que parece una cadena aleatoria cualquiera es indetectable; uno con prefijo salta la alarma antes de que lo encuentre otro.
Corolario: no la transformes. No la partas en dos variables, no la codifiques en base64 «para que no se vea». Si la disfrazas, los escáneres dejan de reconocerla y pierdes justo la red que el prefijo te daba.
El «último uso» está para detectar filtraciones
En cada petición válida el servidor apunta tres cosas, visibles en la lista del panel:
| Dato | Para qué |
|---|---|
| Último uso | Una clave con meses sin usarse es una clave que sobra: revócala. |
| IP del último uso | Ésta es la señal. Si tu CI corre en GitHub y ves un uso desde una IP residencial de otro país, la clave se ha filtrado. Se guarda en claro justamente para eso: un hash no te dejaría reconocer tu propia máquina. |
| Número de usos | Un salto de 12 a 400 en un día no es tu CI. |
No es analítica: es lo mínimo para poder decir «esta clave está comprometida» antes de que aparezca un binario que tú no subiste.
Revocar
Panel → claves de API → Revocar. Es inmediato: la siguiente petición que llegue con ella responde 401.
Es irreversible, y a propósito: la fila no se borra, se marca. Así el historial de quién publicó qué sigue teniendo a quién atribuírselo.
Si se te filtra
En este orden:
- Revócala en el panel. Primero eso; lo demás puede esperar cinco minutos.
- Crea otra y actualiza el secreto del repositorio.
- Revisa las versiones de tu aplicación. Cualquiera que no reconozcas, retírala desde el panel con el motivo puesto. Una versión publicada no se puede borrar; retirar sí, y además deja constancia.
- Si el binario llegó a servirse, avísanos. Preferimos enterarnos tarde que no enterarnos.