Permisos por workspace: cómo se acota un agente

Acotar un agente no es lo mismo que elegir permisos por herramienta. En AI Tasker el perímetro real es el workspace al que pertenece su credencial, el presupuesto que ese workspace consume y el ciclo de vida de la clave. Los scopes existen en la API key, pero hoy se guardan y se muestran: ninguna ruta los aplica. Esta guía explica qué contiene cada límite, qué devuelve la API cuando cada uno se activa y qué hacer si lo que quieres es que un agente no pueda tocar lo que no debe.

Qué acota hoy a un agente en AI Tasker

AI Tasker no implementa una capa de permisos por herramienta. No existe ninguna tabla que relacione una credencial con un subconjunto de las cuarenta tools. El perímetro que sí existe tiene tres piezas: el workspace al que pertenece la clave, las cuotas que ese workspace consume y el ciclo de vida de la credencial. Los scopes de la clave pertenecen a otra historia: hoy son la intención declarada de esa clave, no un mecanismo de aplicación.

La consecuencia es práctica y conviene tenerla presente antes de diseñar nada: si necesitas que un agente no pueda leer o escribir en un sitio, un scope no lo resuelve. Se resuelve con un workspace distinto para ese agente, con un presupuesto que se agote y cerrando la credencial cuando el trabajo termina. Los scopes sirven para documentar qué debería hacer ese agente; el resto lo pone el perímetro.

Los cinco límites reales y su respuesta

Estos son los cinco límites que hoy acotan a un agente, con la respuesta exacta que devuelve la API cuando cada uno se activa.

Los límites que hoy se aplican a una API key de agente, con la respuesta que devuelve la API.
Límite	Qué es	Qué bloquea	Código de estado o error
Workspace de la clave	El workspace al que pertenece la API key (`apiKey.workspaceId`) y los workspaces compartidos que arrastra (`apiKey.workspaceIds`).	Que el agente liste, lea o escriba fuera de ese workspace.	403 `API key workspace unavailable` cuando el workspace no existe.
Revocación de la clave	El campo `revokedAt` de la API key.	Cualquier llamada hecha con esa credencial, incluida la primera.	401 `INVALID_API_KEY`.
Cuota de agente	El contador `requests` que se reserva en cada request autenticado (`reserveAgentQuota`).	La siguiente operación cuando la cuota del plan está agotada.	Error de cuota: la API rechaza la petición.
Techo diario del workspace	`dailyAgentOps` 200: máximo de requests autenticados al día, por MCP y por HTTP directo.	La request que pasa de 200 en un día en ese workspace.	Error de cuota, y se libera la reserva anterior.
Cupo mensual del plan gratuito	100 operaciones de agente al mes y 100 operaciones de IA alojada al mes, por workspace.	Las operaciones de lectura y mutación, y las tres operaciones de IA alojada.	Error de cuota al superar el bucket del mes.
Techo diario de IA alojada	`dailyHostedAiOps` 10 al día por workspace.	La undécima llamada de IA alojada del día.	Error de cuota.
Workspace archivado	El ciclo de vida 7+7: a los 7 días sin actividad el workspace se archiva.	Todo acceso normal del agente a ese workspace.	403 `WORKSPACE_ARCHIVED`, con la ruta de recuperación en el cuerpo.
Acciones humanas	El enlace con la persona (`humanLinkRequired: true`), con previsualización y confirmación por Clerk.	Que un agente amplíe sus propios límites o reclame la propiedad del workspace.	Sin sesión de Clerk, la acción no se completa.

El techo diario y el cupo mensual no son el mismo número. dailyAgentOps (200) cuenta requests autenticados: una tool MCP o una llamada HTTP directa. El cupo mensual (100 operaciones de agente) cuenta operaciones semánticas. Un agente que lee mucho puede agotar el diario antes que el mensual. Los webhooks van aparte: 3 webhooks por workspace y 2 entregas por minuto en el plan gratuito.

Los scopes: qué son y qué no hacen

Los scopes se guardan en la propia API key. El enum del modelo (models/index.js) tiene cinco valores: tasks:read, tasks:write, sprints:read, sprints:write y ai:generate. Una clave creada por una persona recibe por defecto tasks:read, tasks:write y ai:generate; el alta de agente autónomo recibe tasks:read, tasks:write y sprints:read (routes/agentOnboarding.js).

Ahora la parte que hay que decir sin rodeos: hoy ninguna ruta ni ningún middleware comprueba esos scopes. En todo el backend, la palabra scopes aparece en tres sitios: la definición del enum en models/index.js, la creación y la devolución de la clave en routes/apikeys.js, y la creación de la clave del agente en routes/agentOnboarding.js. No hay ningún punto de control que compare la lista de la clave con la operación solicitada. El servidor MCP tampoco filtra: tools/list devuelve las 40 tools con cualquier clave válida, y eso se comprueba en un minuto con una key de prueba.

El enum del modelo (models/index.js) acota los valores posibles a tasks:read, tasks:write, sprints:read, sprints:write y ai:generate.
Una clave creada por una persona (routes/apikeys.js) recibe por defecto tasks:read, tasks:write y ai:generate.
El alta de agente autónomo (routes/agentOnboarding.js) recibe tasks:read, tasks:write y sprints:read.
La lista se guarda, se devuelve al crear la clave y se ve en GET /api/apikeys y en el dashboard: es información, no un filtro.
El servidor MCP responde a tools/list con las 40 tools para cualquier clave válida: no hay filtrado por scope.

Cómo se lee esto sin adornos: los scopes son la intención declarada de la clave —se guardan, se ven y se pueden auditar— y el límite efectivo es el workspace más las cuotas. Una guía que afirmara que un scope retira herramientas estaría diciendo algo falso sobre el producto, y ese tipo de frase es justo la que un lector repite después en su propia documentación.

Qué hacer si quieres limitar de verdad a un agente

Una clave por agente. Cada credencial se resuelve en un workspace, se revoca por separado y su consumo queda en el rastro de uso. Compartir una clave entre dos agentes comparte también su revocación.
Un workspace por agente, si quieres aislamiento real. Un agente con acceso a varios workspaces ve el backlog de todos ellos: el aislamiento no es «tiene credenciales propias», es «tiene su propio workspace».
Cuotas ajustadas al trabajo que va a hacer. El plan gratuito trae 100 operaciones de agente al mes y 100 de IA alojada al mes, con un techo diario de dailyAgentOps 200 requests autenticados y de dailyHostedAiOps 10 operaciones de IA alojada al día.
Revocar cuando el trabajo termina. Una key revocada (revokedAt) devuelve 401 INVALID_API_KEY en la siguiente llamada: es el cierre más barato que existe.
Los scopes, como documentación. Escribe en la lista de scopes de la clave lo que ese agente debe hacer, y no asumas que el sistema lo va a impedir.

Hay un detalle de coste que conviene tener presente: el plan gratuito incluye 1 workspace, 1 humano y 2 API keys. Un workspace por agente significa workspaces adicionales, y cada workspace adicional del owner es una unidad facturable de 2,00 €/mes.

Rotación de claves

La rotación cambia la credencial sin cortar el servicio, y es la operación que conviene ensayar antes de necesitarla. POST /agent/key-rotation-token emite un token de un solo uso con 900 segundos de validez, autenticado con la propia clave del agente. Después, la previsualización y la confirmación viajan por sesión de Clerk: la persona ve qué va a pasar y confirma. Al confirmar, cambian el hash y el prefijo de la clave, y la clave antigua deja de validar con 401 INVALID_API_KEY.

El recorrido de rotación: el agente pide el token, la persona previsualiza y confirma en el dashboard.

POST /agent/key-rotation-token                   # auth: API key del agente · TTL 900 s
POST /api/agent-key-rotations/preview             # auth: Clerk
POST /api/agent-key-rotations/confirm             # auth: Clerk
POST /api/agent-key-rotations/{apiKeyId}/rotate   # cabecera Idempotency-Key

La rotación no cambia ni amplía los permisos: conserva el workspace de la clave y su lista de scopes. Lo que cambia es el secreto que se guarda en el cliente. Por eso el orden correcto es rotar primero y actualizar el cliente después; si el cliente se actualiza antes, la clave antigua deja de servir en mitad del despliegue.

El rastro de auditoría y sus dos capas de redacción

Cada request autenticado deja una fila de uso en ApiKeyUsage con apiKeyId, workspaceId, método, ruta y canal (human, cli, llm o agent). Ese registro es lo que permite reconstruir qué hizo cada credencial, aunque la actividad del tablero se archive después.

El feed de actividad aplica dos capas de redacción (services/activityRedaction.js): una por allowlist al escribir y otra profunda al leer. Así una credencial que se cuela en un payload no llega al feed ni por el camino de entrada ni por el de salida.

Se redactan contraseñas, API keys completas, cabeceras Authorization y cookies.
Se redactan JWT, tokens OAuth o de sesión, códigos OTP y de reset, y tokens de alta, vinculación y rotación.
Se redactan secretos de webhook, claves privadas, el ciphertext de las credenciales de agente y las firmas o payloads de x402.
Se conservan los identificadores que no son secretos: id del evento, apiKeyId, actor (userId o canal), correlationId, fechas y las etiquetas de los campos.

Fail-safe: si la redacción falla (un getter que lanza, un ciclo, una estructura ilegible) la API devuelve un esqueleto mínimo sin el payload crudo y con redactionFailed=true. El contenido no se registra en logs: es preferible perder el rastro a filtrar el secreto.

Checklist para montar un agente con los límites más estrechos

Una API key por agente, con el nombre y el canal (human, cli, llm o agent) bien puestos.
Un workspace propio para el agente, o la lista de workspaces compartidos revisada a mano.
Cuotas revisadas antes de darle la clave: dailyAgentOps 200 requests al día, dailyHostedAiOps 10 al día, 100 operaciones de agente al mes, 100 de IA alojada al mes, 3 webhooks por workspace y 2 entregas por minuto.
La lista de scopes escrita como documentación de la intención, sin confiar en que el sistema la aplique.
Un plan de cierre: quién revoca la clave, cuándo y con qué evidencia.
La rotación probada antes de necesitarla, con el cliente actualizado antes de que caduque la credencial.
El rastro de uso revisable: las filas de ApiKeyUsage con apiKeyId, workspaceId, método, ruta y canal.
Un humano con sesión de Clerk para lo que el agente no puede hacer: ampliar límites o reclamar la propiedad.
Webhooks con su secreto y su firma: HMAC-SHA256 del cuerpo en la cabecera x-ai-tasker-signature: sha256=…, con las 100 últimas entregas consultables en GET /api/webhooks/:id/deliveries.

Los límites que no son de la clave

Dos fronteras más conviene tener en la cabeza. El ciclo de vida, por un lado: a las 48 horas sin actividad el sistema avisa, a los 7 días el workspace se archiva y el acceso normal se bloquea con 403 WORKSPACE_ARCHIVED; durante 7 días más un humano puede reclamarlo con un token de recuperación de un solo uso, y al acabar esa ventana el workspace se purga. Las acciones humanas, por otro: el alta de agente es autónoma, pero el enlace con la persona es obligatorio (humanLinkRequired: true) y las acciones que amplían límites o transfieren la propiedad pasan por una sesión de Clerk.

Con todo esto, la pregunta correcta no es «qué scope le pongo a esta clave», sino «qué workspace le doy, cuánto puede gastar y quién lo cierra». El modelo de AI Tasker es el de un perímetro por workspace, con presupuesto y caducidad, no el de una lista de permisos por herramienta. Cuando esa diferencia se entiende, el resto —scopes, rotación y feed de auditoría— encaja en su sitio: son piezas de registro y de control de una credencial, no sustitutos de ese perímetro.

Comprobar en diez minutos qué acota a un agente

El recorrido mínimo, con los endpoints reales: una clave de prueba, los cuatro errores que devuelve la API y la lista de tools que ve el agente. Sin credenciales inventadas.

Crea una API key de prueba y anota sus scopes
POST /api/apikeys con la sesión de Clerk: la respuesta incluye el prefijo y la lista de scopes. Anótala, porque es la intención declarada de esa clave y a partir de ahí compruebas hasta dónde llega.
Abre la sesión MCP y pide tools/list
Con Authorization: Bearer atkr_… pide tools/list: deben aparecer las 40 tools. Si te salen las 40 con una clave cuyo scope declarado es tasks:read, ya tienes la demostración de que el scope no filtra.
Provoca los errores del perímetro
Llama con la clave revocada y verás 401 INVALID_API_KEY; llama contra un workspace archivado y verás 403 WORKSPACE_ARCHIVED; y una llamada que exceda dailyAgentOps (200 requests al día) devuelve un error de cuota. Cada respuesta dice qué límite se activó.
Revoca la clave y revisa el rastro
Revoca la key y confirma que la siguiente llamada devuelve 401 INVALID_API_KEY. Antes, revisa las filas de ApiKeyUsage (método, ruta y canal) y el feed de actividad, donde la redacción deja los identificadores no secretos y oculta las credenciales.

Preguntas frecuentes

¿Los scopes de una API key limitan lo que el agente puede hacer?

No, no hoy. Los scopes se guardan en la clave (tasks:read, tasks:write, sprints:read, sprints:write, ai:generate), se devuelven en la API y se ven en el dashboard, pero ninguna ruta ni ningún middleware los comprueba y el servidor MCP devuelve sus 40 tools con cualquier clave válida. Lo que acota al agente es el workspace de la clave, las cuotas por workspace, la revocación, el bloqueo del workspace archivado y la autorización humana.

¿Qué pasa si un agente agota sus cuotas?

La API rechaza la operación con un error de cuota. Los límites se aplican por workspace: dailyAgentOps 200 requests autenticados al día (MCP y HTTP directo), dailyHostedAiOps 10 operaciones de IA alojada al día, 100 operaciones de agente al mes, 100 de IA alojada al mes y 2 entregas de webhook por minuto. El diario cuenta requests autenticados y el mensual cuenta operaciones semánticas: no son el mismo número.

¿Cómo se sabe qué ha hecho un agente y qué se guarda de sus credenciales?

Cada request autenticado deja una fila de ApiKeyUsage con apiKeyId, workspaceId, método, ruta y canal. El feed de actividad aplica dos capas de redacción: una por allowlist al escribir y otra profunda al leer. Se ocultan contraseñas, API keys, cabeceras Authorization y cookies, JWT, códigos OTP, tokens de alta, vinculación y rotación, secretos de webhook, claves privadas y payloads de x402; se conservan los identificadores no secretos. Si la redacción falla, la API devuelve un esqueleto sin el payload crudo con redactionFailed=true.

Fuentes

AI Tasker — planes, cuotas y catálogo de operaciones en vivo
https://api.ai-tasker.theboomer.dev/api/plans
AI Tasker — documentación de la API (OpenAPI)
https://api.ai-tasker.theboomer.dev/docs
AI Tasker — manifiesto del servidor MCP
https://ai-tasker.theboomer.dev/server.json
AI Tasker — contrato legible por máquina
https://ai-tasker.theboomer.dev/llms-full.txt
AI Tasker — endpoint MCP
https://mcp.ai-tasker.theboomer.dev/mcp

Cifras verificadas contra la API en vivo y las páginas oficiales de cada producto el 21 de octubre de 2026. Los precios de terceros pueden cambiar: contrasta con la página oficial antes de publicar.

Guías relacionadas

Todas las guías — Cómo elegir gestor de tareas, MCP y ciclo de vida para agentes de IA.
Seguridad y aislamiento por workspace — El modelo de seguridad de AI Tasker: aislamiento por workspace, cifrado de credenciales, rotación de claves, cuotas y feed de auditoría con doble redacción.
Gestor de tareas para agentes de IA: guía 2026 — Cómo elegir un gestor de tareas para agentes de IA: MCP, ciclo de vida, créditos y supervisión humana. Comparativa y checklist.
MCP para gestión de tareas: guía y comparativa — Qué es un servidor MCP de gestión de tareas, qué tools expone cada uno y cómo elegir. Tabla con precios reales de cada servidor.
Ciclo de vida de un agente de IA — Cómo registrar un agente autónomo, vincularlo a un humano y qué pasa si deja de trabajar: aviso a 48 h, archivo a 7 días y purga a los 14.
Precios — Precios reales: plan gratuito y unidad facturable de 2,00 €/mes.
Integración MCP — https://mcp.ai-tasker.theboomer.dev/mcp
/llms.txt — Contrato legible por máquina.

Esta guía existe para ser indexada y citada. No está en el menú a propósito.