Los permisos de una clave API deciden qué puede romper una clave filtrada. En una herramienta de enlaces, lo seguro por defecto es una clave ligada a un único espacio de trabajo, limitada al rol más bajo que haga el trabajo, guardada como hash con pepper, con su propio límite de tasa y con 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 el mínimo privilegio, y casi todo se reduce a decisiones que tomas en los treinta segundos que lleva crear 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 pensar en ello hasta que esa persona se va o la exportación del flujo acaba en una unidad compartida. El resto de este artículo explica cómo funcionan los scopes y roles de 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.
Complementa nuestra checklist de seguridad de acortadores de URL, más amplia, que cubre escaneo, firma de webhooks y registros de auditoría en toda la plataforma. Este artículo se centra en la clave en sí.
Qué significan los permisos de claves API en una herramienta de enlaces
La API de una herramienta de enlaces toca más que enlaces. El mismo token que crea go.example.com/spring-sale puede, según sus permisos, leer analítica 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 me da miedo. Un webhook es un flujo de datos permanente que quien lo crea puede apuntar al servidor que quiera, y nadie de tu equipo tiene por qué enterarse en semanas.
Así que los permisos tienen tres ejes. ¿Dónde funciona la clave (qué cuenta o espacio de trabajo)? ¿Qué puede hacer allí (leer, escribir, administrar)? ¿Y durante cuánto tiempo y a qué velocidad? La definición del glosario del NIST de mínimo privilegio (consultado el 2026-10-24) dice que cada entidad recibe las autorizaciones mínimas que necesita para cumplir su función, y los tres ejes forman parte de eso. Una clave de solo lectura que nunca caduca y no tiene límite de tasa sigue teniendo demasiados privilegios en el tiempo.
Claves API ligadas al espacio de trabajo: una clave, un espacio de trabajo
En Elido, cada clave se emite dentro de un espacio de trabajo y se queda allí. Si la usas para llamar a los endpoints de otro espacio de trabajo recibes un 404, la misma respuesta que para un espacio de trabajo que no existe, de modo que una clave ni siquiera puede confirmar que los demás espacios de trabajo están ahí.
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 su creador puede alcanzar, un solo token filtrado de un proyecto de cliente abriría todos los clientes. Las claves API ligadas al espacio de trabajo reducen el radio de impacto a un espacio de trabajo.
La clave también está limitada al rol elegido al crearla y nunca supera el rol actual de su creador. El acceso efectivo es el menor de los dos. Si degradas a editor al admin que creó una clave, la clave baja con él. Los permisos personalizados asociados a ese miembro también se descartan 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 lo omites, la clave toma editor por defecto, que cubre la tarea habitual de automatización de crear enlaces y leer analítica sin alcance de administración.
Así se ve en la práctica para lo que suelen tocar las integraciones.
| Rol | Enlaces y campañas | Analítica | Webhooks | Dominios, miembros, claves |
|---|---|---|---|---|
| viewer | Solo lectura | Leer, iniciar trabajos de exportación CSV | Listar endpoints | Ver dominios y miembros |
| editor | Crear, editar, borrar, crear en masa | Leer, iniciar trabajos de exportación CSV | Listar endpoints | Ver dominios y miembros |
| admin | Todo lo que puede el editor | Más configuración de exportación de datos a S3 e informes programados por email | Crear, cambiar, reenviar (replay) | 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. Un trabajo de Google Sheets que genera enlaces de campaña necesita editor. Casi nada de la automatización diaria necesita admin, y yo consideraría una clave de owner un mal olor: owner existe para las personas que dirigen el espacio de trabajo, y no se me ocurre ninguna tarea de automatización que lo necesite.
Conviene conocer dos límites. Solo los admins y owners tienen el permiso api_keys.manage, así que una clave de viewer o editor no puede listar ni revocar claves. Y crear una clave, o cambiar su límite de tasa, requiere a una persona con sesión iniciada: una clave API de cualquier rol recibe un 403 ("this action requires an interactive session"). Una clave de admin filtrada no puede generar un reemplazo sin caducidad. Aun así, puede listar y revocar claves. Y ninguna clave de ningún rol llega a la API de administración de la plataforma. Esa superficie rechaza la autenticación por clave API con un 403 y el mensaje "admin access requires an interactive session". Una clave es para una integración de espacio de trabajo, y eso es todo lo que abre.
Por qué gestionar webhooks requiere una clave de admin
Esto es lo que sorprende a la gente. Leer la lista de endpoints de webhook está permitido a cualquier miembro, incluidas las claves de viewer. Pero crear un endpoint, cambiar adónde apunta o reenviar (replay) una entrega requiere el permiso workspace.edit, que solo tienen admin y owner.
El razonamiento es el problema del flujo permanente de antes. Un editor puede crear mil enlaces y te darás cuenta. Un editor que pudiera añadir un webhook comodín apuntando a su propio servidor recibiría desde ese momento todos los eventos de enlaces, en silencio. 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 sola vez, a mano, como admin en el panel. Luego da a la automatización que los consume una clave de editor o viewer para sus llamadas a la API. Si estás conectando webhooks de eventos de enlaces a Slack o a un CRM, el lado receptor no necesita ninguna clave de Elido; necesita el secreto de firma para verificar los payloads.
¿Quieres una prueba antes de conectar nada? Crea un espacio de trabajo gratuito, genera una clave de viewer y una de editor y prueba la misma llamada de escritura con cada una. El 403 de la clave de viewer te dice más que cualquier tabla.
Cómo se guardan las claves: pepper, hash y prefijo
Un token tiene el aspecto elido_ seguido de 52 caracteres en base32, generados a partir de 32 bytes aleatorios. Lo ves completo exactamente una vez, en la respuesta a la llamada de creación. Después desaparece de nuestro lado para siempre.
Lo que guardamos es un HMAC-SHA256 del token, con la clave de un pepper del servidor que vive en la configuración de la aplicación, no en la base de datos. En cada petición, el token Bearer entrante (el esquema definido en el RFC 6750, consultado el 2026-10-24) se procesa con el mismo hash y se busca por hash. Así que un volcado robado de la base de datos es una lista de hashes que nadie puede comprobar sin el pepper. Sin pepper no hay arranque: el servicio de producción se niega a iniciarse si no hay uno configurado.
Para tus propios registros guardamos los primeros ocho caracteres después de elido_ como prefijo visible, y la página de claves API muestra ese prefijo junto al nombre de la clave, su rol, fecha de creación, caducidad, hora del último uso e IP del último uso, junto con los recuentos de peticiones totales y fallidas. Cuando una clave aparece en un log en algún sitio, el prefijo te dice cuál es. Nadie tiene que ver el secreto completo.
Límites de tasa, caducidad y rotación de claves API
Cada clave tiene su propio token bucket, separado del límite por espacio de trabajo, para que un flujo descontrolado no consuma el presupuesto de todo lo demás. Un admin con sesión iniciada puede sobrescribir la tasa de una sola clave de 1 a 10.000 peticiones por segundo y su ráfaga (burst) de 1 a 20.000, o eliminar la sobrescritura para volver al valor por defecto. Al superar el límite, la clave recibe un 429 con Retry-After: 1 y X-RateLimit-Scope: api_key, de modo que tu lógica de reintentos distingue el tope de una clave del tope de un espacio de trabajo. La guía de límites de tasa e idempotencia explica cómo aplicar un backoff correcto.
La caducidad es opcional y se fija al crear como una marca de tiempo RFC 3339. Cuando pasa, la clave simplemente deja de coincidir. La revocación es un DELETE. Y es idempotente.
No hay un único botón de "rotar", y no lo echo de menos. La rotación son tres pasos:
- Crea una clave nueva con el mismo rol y una caducidad nueva.
- Cámbiala en el almacén de credenciales de la herramienta y confirma que una llamada tiene éxito.
- Revoca la clave antigua y comprueba en la lista que su hora de último uso ha dejado de avanzar.
Cada paso queda en el 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 las sobrescrituras. Un escaneo en segundo plano se ejecuta cada cinco minutos y marca cualquier clave con más de 1.000 peticiones de las que más del 30 % fallaron. La marca se guarda en el registro de auditoría y en la clave. No hay revocación automática. Cortar una clave es una decisión humana, porque una ráfaga de 404 es tan a menudo un flujo roto como 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 ser olvidadas. Se quedan en un almacén de credenciales, se copian en el JSON exportado de los flujos y sobreviven a la persona que las configuró. Ayudan dos hábitos:
- Una clave por herramienta y por familia de flujos, con el nombre de esta ("n8n: campaign sheets"). Revocarla rompe exactamente una cosa, y el registro de auditoría dice qué herramienta hizo qué.
- Editor para todo lo que crea enlaces, viewer para todo lo que solo lee, y una fecha de caducidad en ambos.
Esa es toda la lista; el resto es criterio. La Secrets Management Cheat Sheet de OWASP (consultado el 2026-10-24) es una buena lectura sobre cómo mantener los tokens fuera de logs y exportaciones, que es donde suelen filtrarse las claves de automatización.
Para la configuración específica de cada herramienta, la guía del acortador de URL para n8n pone la clave en una credencial Header Auth, y la comparativa Make vs IFTTT vs n8n vs Zapier explica dónde la guarda cada plataforma. Zapier se conecta con el mismo token, según el recorrido de automatización con Zapier. Para CI o cualquier cosa que deba sobrevivir a la salida de una persona, encaja mejor un machine user: una cuenta de servicio con su propio token, separada de la clave de cualquier persona. Como las claves, los machine users los crea un admin con sesión iniciada, nunca un token.
Y la razón por la que una clave nunca debe abrir endpoints de administración es precisamente esta entrega. Cuando un token vive en una herramienta de terceros, cualquiera con acceso de edición a los flujos de esa herramienta puede usarlo. Confías en todos los de su lado, no solo en los tuyos.
Los tokens por scope están previstos, no disponibles
Los roles son gruesos a propósito, y a veces demasiado. Una clave de editor que solo crea enlaces también puede borrarlos, porque borrar forma parte del rol de editor. La solución son tokens por scope, como links:write o analytics:read, asociados directamente a una clave y apilados sobre los roles.
Está en nuestra hoja de ruta y no se ha lanzado. Hoy, los permisos de una clave son su espacio de trabajo más su rol, y nada más fino. Si necesitas un control más estricto ahora, las dos palancas son un rol más bajo y una caducidad corta, y claves separadas por tarea para que el radio de impacto de cada una sea pequeño. El quickstart de la API y la referencia de API y SDK muestran el modelo de claves actual en código funcional, y los equipos que además quieran control a nivel de identidad pueden leer sobre SCIM y SSO para herramientas de marketing.
Lee el cornerstone: la checklist de seguridad de acortadores de URL cubre los controles que rodean a la clave, desde el escaneo de URL hasta las listas de IP permitidas.
Relacionados en el blog
- API de acortador de URL: quickstart de 30 minutos en cinco lenguajes
- Acortador de URL para n8n: nodo HTTP Request o nodo de la comunidad de Elido
- Automatización de enlaces cortos: Make vs IFTTT vs n8n vs Zapier
- Webhooks para eventos de enlaces
- Acortador de URL en 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 cambiar y en qué cuenta. En Elido, los permisos de una clave provienen del espacio de trabajo en el que 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é es el mínimo privilegio para claves API?
Significa que cada clave recibe el menor conjunto de permisos que necesita su tarea y nada más. Un panel que solo lee recuentos de clics recibe una clave de lector (viewer), un flujo que crea enlaces recibe una clave de editor, y las claves de admin se reservan para la rara tarea que gestiona webhooks, dominios o miembros. Así, una clave filtrada solo puede hacer lo que hacía esa tarea.
¿Cuál es la diferencia entre scopes y roles de claves API?
Un scope es un permiso concreto como links:write asociado directamente a un token, mientras que un rol es un paquete con nombre de permisos como editor. Los roles son más fáciles de razonar; los scopes son más finos. Las claves de Elido usan hoy roles de espacio de trabajo, y los tokens por scope están previstos encima de ellos pero todavía no están disponibles.
¿Con qué frecuencia deben rotarse las claves API?
La recomendación habitual es cada 30 a 90 días, y de inmediato cuando se va alguien que vio la clave, la clave aparece en un log o su tráfico parece anómalo. Fijar una fecha de caducidad al crearla convierte ese calendario en un tope firme en lugar 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 con inicio de sesión y responde con un 403 a una clave API, sea cual sea el rol de quien la creó. Los ajustes del espacio de trabajo que requieren permisos de admin siguen siendo accesibles, pero solo con una clave creada con el rol de admin o propietario.
¿Cómo debe guardar el proveedor las claves API?
Nunca en texto plano. El proveedor debe guardar un hash con clave del token y mostrarte después solo un prefijo corto, de modo que una copia de la base de datos por sí sola no sirva para llamar a la API. Elido aplica a cada token un HMAC-SHA256 con un pepper 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.
Sin registro. Crea una cuenta gratis y obtén 50 enlaces al mes.