El problema que todos ya vivimos
¿Te ha pasado que necesitas darle acceso a un compañero nuevo, a un pipeline de CI/CD, o — más reciente — a un agente de IA que va a tocar tu infra? La tentación siempre es la misma: "dale un token de Admin y ya". Pero ahí rompes el principio de menor privilegio de una forma brutal. Un token filtrado con Workers Scripts Edit significaba acceso a TODOS los Workers de tu cuenta. Incluso el que sirve producción. 😱
Cloudflare acaba de lanzar control de acceso por Worker con cuatro roles nuevas, que te permiten escopar hasta un recurso específico. Es el primer paso hacia un modelo de autorización consistente en toda la Developer Platform (D1, R2 y KV vienen en camino).
Vamos a ver qué cambió en la práctica y cómo migrar sin romper tu pipeline. ¡Vamos a darle! 🚀
Las cuatro roles nuevas
En lugar de ese blob genérico de "Workers Admin", ahora eliges una role (qué puede hacer) y un scope (en qué recursos).
| Role | Qué permite | Cuándo usarla |
|---|---|---|
| Metadata Read-Only | Ver listas, settings, métricas, logs y traces. Sin acceso al contenido. | Agente de debug o guardia que necesita observabilidad, pero no el código. |
| Content Read-Only | Leer código del Worker / contenido de D1. Sin escritura. | Bots de code review, auditoría de seguridad, dev nuevo en el equipo. |
| Editor | Leer + escribir contenido y actualizar settings. No crea ni borra. | Tokens de CI/CD, agentes que hacen deploy. |
| Admin | Control total, incluyendo borrar y otorgar acceso. | Dueño de un Worker específico, nada más. |
Scopes: tres niveles
Cada role se puede aplicar en uno de estos niveles:
- Developer Platform — todos los recursos de la plataforma.
- Producto — todos los recursos de un producto (ej: todos los Workers).
- Recurso — un Worker específico, una DB D1, un bucket.
Creando un token escopado a un Worker
En el dashboard, al crear el token, seleccionas el Worker como scope. El wrangler.toml sigue igual — quien limita el daño es el token, no el archivo:
# wrangler.toml
name = "mi-worker"
main = "src/index.ts"
compatibility_date = "2024-09-23"
# La ruta es permiso aparte — necesitas
# Workers Routes en la zona para tocar esto.
[[routes]]
pattern = "ejemplo.mx/*"
zone_name = "ejemplo.mx"
# Crea un token escopado a UN Worker con role Editor
# (dashboard: Manage Account > Members > API Tokens)
export CLOUDFLARE_API_TOKEN="<token-escopado>"
# Este deploy solo toca mi-worker, aunque el token se filtre.
npx wrangler deploy
Durable Objects heredan del Worker
Durable Objects no tienen roles propias. El acceso viene del Worker que los implementa. Para debuggear un DO, dale Metadata Read-Only al Worker. Para consultar o modificar estado vía Data Studio, necesita Editor.
Mapa de migración: roles viejas → nuevas
Cloudflare no va a deprecar las roles viejas (por ahora), pero conviene migrar ya — solo las nuevas soportan scope a nivel de recurso.
| Role vieja | Role nueva recomendada |
|---|---|
| Workers Platform (Read-Only) | Developer Platform Content Read-Only |
| Workers Platform Admin | Developer Platform Admin |
| Workers Scripts Read | Content Read-Only |
| Workers Scripts Edit | Editor |
| Workers CI Read | Content Read-Only |
| Workers CI Edit | Editor |
| Workers Observability Read | Metadata Read-Only |
| Workers Observability Edit | Editor |
| Workers Observability Telemetry Edit | Editor |
| Workers Tail Read | Metadata Read-Only |
Límites y trampas 🧐
- Rutas y Custom Domains son permiso aparte. Editar una ruta requiere Editor en el Worker + Workers Routes en la zona. Es intencional — no quieres que un token de CI redirija tráfico de producción en silencio.
- Deploys que no tocan rutas son seguros. Una vez configurada la ruta, el CI puede subir nuevas versiones sin acceso a la zona.
- Datos de Durable Object están detrás de Editor. Metadata Read-Only no te deja inspeccionar estado vía Data Studio.
- Sin fecha de deprecación de las roles viejas. Asignaciones existentes siguen funcionando, pero pierdes el beneficio del scope.
- Errores 403 mejores. Ahora las APIs linkean a la doc exacta de permisos — útil cuando tu agente necesita autodiagnosticarse.
Próximos pasos
- Audita tus tokens de API. Todo token con
Workers Scripts Edites candidato a convertirse en Editor + scope en Worker. - Crea User Groups para equipos con el mismo patrón de acceso, en vez de asignar persona por persona.
- Re-tokeniza tu CI/CD. Cada pipeline tiene su propio Editor escopado al Worker que despliega.
- Escopea tus agentes. Si el agente solo debuggea, dale Metadata Read-Only — no Editor.
- Pon atención al rollout de D1 / R2 / KV. Las mismas cuatro roles van a aplicar; ya estandariza tu nomenclatura.
Referencia completa en la documentación de autorización de Cloudflare Workers.
El punto real
Lo interesante de este release no son las cuatro roles — tabla de RBAC es aburrida. Es que Cloudflare está tratando a los agentes de IA como identidades de primera clase, que merecen tokens propios y escopados. Es un cambio silencioso pero importante: el modelo de amenaza ahora incluye actores no-humanos que llaman tus APIs por su cuenta.
Si ya corres agentes contra tu infra, esto es obligatorio en tu stack. Si aún no, empieza escopeando los tokens del CI — la disciplina es la misma.
Lee también
- Beyond Demos: Building Production-Ready AI Agents with Gemini 3 & 6 Open-Source Frameworks — cómo llevar agentes a producción de verdad, no solo a demo.
- From Monolith to Millisecond Latency: The Event-Driven Blueprint Behind Amazon Key — por qué least-privilege y arquitectura event-driven van de la mano a escala.