Los permisos de una clave API determinan qué puede comprometer una clave filtrada. En una herramienta de enlaces, el valor predeterminado seguro es una clave vinculada a un solo espacio de trabajo, limitada al rol más bajo que permite hacer el trabajo, almacenada como un hash con pepper, con su propio límite de velocidad y fecha de caducidad. Una clave que solo crea enlaces no tiene por qué tocar webhooks, miembros ni facturación, y nunca debería abrir un endpoint de administración. Eso es mínimo privilegio, y la mayor parte depende de decisiones que tomas en los treinta segundos que tarda en crearse la clave.
He revisado muchas configuraciones de automatización durante el último año, y el patrón se repite: alguien pega su propia clave todopoderosa en n8n un viernes por la tarde, funciona y nadie vuelve a pensarlo hasta que esa persona se va o la exportación del flujo termina en una unidad compartida. El resto de esta publicación explica cómo funcionan los alcances y roles de las claves API en un producto de enlaces cortos, qué puede hacer realmente cada rol y cómo entregar una clave a una herramienta de automatización sin entregar el espacio de trabajo.
Se complementa con nuestra lista de comprobación de seguridad para acortadores de URL, que cubre el análisis, la firma de webhooks y los registros de auditoría de toda la plataforma. Esta se centra en la propia clave.
Qué significan los permisos de claves API en una herramienta de enlaces
La API de una herramienta de enlaces abarca más que enlaces. El mismo token que crea go.example.com/spring-sale puede, según sus permisos, leer analíticas de clics, añadir un dominio personalizado, invitar a un miembro o registrar un webhook que envía cada evento a un servidor externo. Este último caso me preocupa. Un webhook es un flujo de datos permanente que quien lo crea puede dirigir a cualquier servidor que quiera, y es posible que nadie de tu equipo se dé cuenta durante semanas.
Por tanto, los permisos tienen tres ejes. ¿Dónde funciona la clave, en qué cuenta o espacio de trabajo? ¿Qué puede hacer allí, leer, escribir o administrar? ¿Y durante cuánto tiempo y a qué velocidad? La definición de mínimo privilegio de NIST se resume en conceder solo el acceso que necesita una tarea, y los tres ejes forman parte de ello. Una clave con permisos de solo lectura que nunca caduca y no tiene límite de velocidad sigue teniendo privilegios excesivos en el tiempo.
Claves API por espacio de trabajo: una clave, un espacio de trabajo
En Elido, cada clave se emite dentro de un espacio de trabajo y permanece allí. Si llamas con ella a los endpoints de cualquier otro espacio de trabajo, recibes un 404, la misma respuesta que para un espacio de trabajo inexistente, por lo que la clave ni siquiera puede confirmar que existan otros espacios de trabajo.
Esto importa más de lo que parece. Las agencias y los equipos grandes suelen pertenecer a cinco o diez espacios de trabajo. Si una clave personal heredara todo lo que puede alcanzar su creador, un token filtrado de un proyecto de cliente abriría a todos los clientes. Las claves API por espacio de trabajo reducen el radio de impacto a un solo espacio de trabajo.
La clave también queda limitada al rol elegido al crearla y nunca supera el rol actual de su creador. El acceso efectivo es el menor de los dos. Degrada de admin a editor a la persona que creó una clave. La clave desciende con esa persona. Los permisos personalizados asociados a ese miembro también se eliminan siempre que el rol de la clave sea el menor, porque describen a la persona, no a la clave.
Claves API basadas en roles: qué puede hacer cada rol
Las claves de Elido usan los mismos cuatro roles que las personas: viewer, editor, admin y owner. Eliges uno al crear la clave; si no indicas ninguno, la clave usa editor de forma predeterminada, que cubre la tarea habitual de automatización de crear enlaces y leer analíticas sin alcance administrativo.
Así se ve en la práctica para lo que suelen usar las integraciones.
| Rol | Enlaces y campañas | Analíticas | Webhooks | Dominios, miembros, claves |
|---|---|---|---|---|
| viewer | Solo lectura | Leer, ejecutar exportaciones CSV | Listar endpoints | Ver dominios y miembros |
| editor | Crear, editar, eliminar, crear masivamente | Leer, ejecutar exportaciones CSV | Listar endpoints | Ver dominios y miembros |
| admin | Todo lo que puede editor | Además, exportaciones de datos e informes programados | Crear, cambiar, reenviar | Gestionar dominios, miembros y claves |
| owner | Todo | Todo | Todo | Todo |
Un panel de informes que lleva recuentos de clics a una herramienta de BI necesita viewer. Una tarea de Google Sheets que crea enlaces de campaña necesita editor. Casi nada de la automatización cotidiana necesita admin, y consideraría una clave owner como una señal de alerta: owner existe para las personas que gestionan el espacio de trabajo, y no se me ocurre ninguna tarea de automatización que lo necesite.
Conviene conocer dos límites. Solo los administradores y propietarios pueden crear, listar o revocar claves, así que una clave viewer o editor no puede crearse a sí misma una clave hermana con más permisos. Y ninguna clave, sin importar el rol, accede a la API de administración de la plataforma. Esa superficie rechaza de plano la autenticación con clave API mediante un 403 y el mensaje "admin access requires an interactive session". Una clave sirve para una integración de espacio de trabajo, y eso es todo lo que abre.
Por qué la gestión de webhooks necesita una clave admin
Esto es lo que sorprende a la gente. Cualquier miembro puede leer la lista de endpoints de webhook, incluidas las claves viewer. Pero crear un endpoint, cambiar adónde apunta o reenviar una entrega requiere el permiso workspace.edit, que solo tienen admin y owner.
El razonamiento es el problema del flujo permanente que mencioné antes. Un editor puede crear mil enlaces y lo notarás. Un editor que pudiera añadir un webhook general dirigido a su propio servidor recibiría en silencio todos los eventos de enlaces a partir de ese momento. Por eso los cambios de webhook quedan en manos de las mismas personas que pueden cambiar los ajustes del espacio de trabajo.
En la práctica, configura los webhooks una vez, manualmente, como admin en el panel. Después, da a la automatización que los consume una clave editor o viewer para sus llamadas a la API. Si conectas webhooks para eventos de enlaces con Slack o un CRM, el lado receptor no necesita una clave de Elido; necesita el secreto de firma para verificar las cargas útiles.
¿Quieres comprobarlo antes de configurar nada? Crea un espacio de trabajo gratuito, emite una clave viewer y una clave editor e intenta la misma llamada de escritura con cada una. El 403 de la clave viewer te dice más que cualquier tabla.
Cómo se almacenan las claves: pepper, hash y prefijo
Un token tiene el aspecto de elido_ seguido de 52 caracteres en base32, generados a partir de 32 bytes aleatorios. Ves el valor completo exactamente una vez, en la respuesta a la llamada de creación. Después desaparece definitivamente de nuestro lado.
Lo que conservamos es un HMAC-SHA256 del token, con un pepper del lado del servidor que reside en la configuración de la aplicación, no en la base de datos. En cada solicitud, el token Bearer entrante, el esquema definido en RFC 6750, se procesa con el mismo hash y se busca por hash. Un volcado robado de la base de datos es una lista de hashes que no se puede comprobar sin el pepper, y el servicio de producción se niega a iniciarse si no hay uno configurado.
Para tus propios registros, almacenamos los primeros ocho caracteres posteriores a elido_ como prefijo de visualización. La página de claves API muestra ese prefijo junto al nombre, rol, fecha de creación, caducidad, hora de último uso e IP de último uso de la clave, además de los recuentos totales y fallidos de solicitudes. Cuando una clave aparece en algún registro, el prefijo te indica cuál es sin que nadie tenga que ver el secreto completo.
Límites de velocidad, caducidad y rotación de claves API
Cada clave recibe su propio cubo de tokens, separado del límite por espacio de trabajo, de modo que un flujo descontrolado no puede consumir el presupuesto de todo lo demás. Un admin puede fijar para una sola clave una tasa personalizada de 1 a 10.000 solicitudes por segundo y una ráfaga de 1 a 20.000, o eliminar ese ajuste para volver al valor predeterminado. Al superar el límite, la clave recibe un 429 con Retry-After: 1 y X-RateLimit-Scope: api_key, así que tu lógica de reintento puede distinguir un límite de clave de un límite de espacio de trabajo. La guía sobre límites de velocidad e idempotencia explica cómo aplicar el backoff correctamente.
La caducidad es opcional y se establece al crear la clave como una marca de tiempo RFC 3339. Una vez superada, la clave simplemente deja de coincidir. La revocación se realiza con un DELETE. También es idempotente.
No hay un único botón de "rotar", y no lo echo de menos. La rotación consta de tres pasos:
- Crea una clave nueva con el mismo rol y una caducidad nueva.
- Sustitúyela en el almacén de credenciales de la herramienta y confirma que una llamada funciona.
- Revoca la clave antigua y, después, comprueba en la lista que su hora de último uso ha dejado de cambiar.
Cada paso llega al registro de auditoría del espacio de trabajo: api_key.created con el nombre y el rol, api_key.revoked y api_key.rate_limit_set para los límites personalizados. Un análisis en segundo plano también se ejecuta cada cinco minutos y marca cualquier clave con más de 1.000 solicitudes de las que más del 30 % hayan fallado. La marca se incorpora al registro de auditoría y a la clave. No hay revocación automática. Desactivar una clave es una decisión humana, porque una ráfaga de 404 suele indicar con la misma frecuencia un flujo roto que un atacante.
Entregar claves API de mínimo privilegio a n8n, Make y Zapier
Las plataformas de automatización son donde las claves van a olvidarse. Permanecen en un almacén de credenciales, se copian al JSON exportado de los flujos y sobreviven a la persona que las configuró. Dos hábitos ayudan:
- Una clave por herramienta y por familia de flujos, con un nombre que la identifique ("n8n: hojas de campaña"). Revocarla entonces rompe exactamente una cosa, y el registro de auditoría indica qué herramienta hizo qué.
- Editor para todo lo que crea enlaces, viewer para todo lo que solo lee y una fecha de caducidad para ambos.
Eso es todo en cuanto a la lista; el resto es criterio. La hoja de referencia de gestión de secretos de OWASP es una buena lectura sobre cómo mantener los tokens fuera de los registros y las exportaciones, que es donde suelen filtrarse las claves de automatización.
Para la configuración específica de cada herramienta, la guía de acortador de URL para n8n coloca la clave en una credencial Header Auth, y la comparación entre Make, IFTTT, n8n y Zapier explica dónde guarda cada plataforma esa clave. Zapier se conecta mediante el mismo token, según la guía de automatización con Zapier. Para CI o cualquier cosa que deba sobrevivir a la salida de una persona, encaja mejor un usuario de máquina: una cuenta de servicio con su propio rol, independiente de la clave de cualquier persona.
Y la razón por la que una clave nunca debe abrir endpoints de administración es precisamente esta entrega. Cuando un token se encuentra en una herramienta de terceros, cualquiera con acceso de edición a los flujos de esa herramienta puede usarlo. Estás confiando en todos los miembros de su lado, no solo en los tuyos.
Los tokens por alcance están previstos, no disponibles aún
Los roles son deliberadamente amplios y a veces demasiado amplios. Una clave editor que solo crea enlaces también puede eliminarlos, porque eliminarlos forma parte del rol editor. La solución son tokens por alcance, como links:write o analytics:read, vinculados directamente a una clave y superpuestos a los roles.
Eso está en nuestra hoja de ruta y aún no se ha lanzado. Hoy los permisos de una clave son su espacio de trabajo más su rol, y no hay nada más preciso. Si ahora necesitas un control más estricto, las dos palancas son un rol inferior y una caducidad corta, además de claves separadas por tarea para que el radio de impacto de cada una sea pequeño. La guía rápida de la API y la referencia de API y SDK muestran el modelo actual de claves en código funcional, y los equipos que también quieren control a nivel de identidad pueden leer sobre SCIM y SSO para herramientas de marketing.
Lee el artículo principal: la lista de comprobación de seguridad para acortadores de URL cubre los controles alrededor de la clave, desde el análisis de URL hasta las listas de IP permitidas.
Contenido relacionado en el blog
- API de acortador de URL: guía rápida de 30 minutos en cinco lenguajes
- Acortador de URL para n8n: nodo HTTP Request o nodo comunitario de Elido
- Automatización de enlaces cortos: Make frente a IFTTT, n8n y Zapier
- Webhooks para eventos de enlaces
- Acortador de URL para GitHub Actions: enlaces cortos desde tu CI
Preguntas frecuentes
¿Qué son los permisos de una clave API?
Son el conjunto de acciones que una clave puede realizar contra una API: qué recursos puede leer, cuáles puede modificar y en qué cuenta. En Elido, los permisos de una clave proceden del espacio de trabajo donde se emitió y del rol elegido al crearla, de modo que la misma clave no puede actuar en otro espacio de trabajo ni por encima de ese rol.
¿Qué significa mínimo privilegio para las claves API?
Significa que cada clave recibe el conjunto más pequeño de permisos que necesita para su tarea y nada más. Un panel que solo lee recuentos de clics recibe una clave viewer, un flujo que crea enlaces recibe una clave editor y las claves admin se reservan para las tareas excepcionales que gestionan webhooks, dominios o miembros. Así, una clave filtrada solo puede hacer lo que hacía esa tarea concreta.
¿Cuál es la diferencia entre los alcances y los roles de las claves API?
Un alcance es un permiso limitado, como links:write, vinculado directamente a un token, mientras que un rol es un conjunto de permisos con nombre, como editor. Los roles son más fáciles de entender; los alcances son más precisos. Las claves de Elido usan actualmente roles de espacio de trabajo, y los tokens por alcance están previstos para añadirse sobre ellos, pero aún no están disponibles.
¿Con qué frecuencia se deben rotar las claves API?
La recomendación habitual es cada 30 a 90 días, y también de inmediato cuando se va alguien que vio la clave, la clave aparece en un registro o su tráfico parece anómalo. Establecer una fecha de caducidad al crearla convierte ese calendario en un corte obligatorio en vez de un recordatorio que la gente ignora.
¿Puede una clave API acceder a endpoints de administración?
En Elido, no. La API de administración de la plataforma solo acepta una sesión interactiva iniciada y responde a una clave API con un 403, sin importar el rol de quien la creó. Los ajustes del espacio de trabajo que requieren permisos de administración siguen siendo accesibles, pero solo con una clave creada con el rol admin u owner.
¿Cómo se deben almacenar las claves API del lado del proveedor?
Nunca en texto sin formato. El proveedor debe almacenar un hash con clave del token y mostrar después solo un prefijo corto, para que una copia de la base de datos por sí sola no pueda usarse para llamar a la API. Elido aplica a cada token HMAC-SHA256 con un pepper del lado del servidor y muestra el token completo exactamente una vez.
Prueba Elido
Pega una URL, obtén un enlace corto
Sin registro. El enlace vive 30 días. Crea una cuenta para conservarlo.
Gratis, sin registro · 2 por día