Los tres permisos
CognitionDesk tiene tres sistemas de permisos y ninguno reemplaza a los otros. Confundirlos es la pregunta de soporte más común — esta página existe para que un 403 te mande al correcto.
Darle a una API key inventory:write no le da al ASISTENTE ninguna tool nueva. Subir a un contacto a staff no le da al asistente una capacidad que no tenía. Cada sistema contesta una pregunta distinta.
El ASISTENTE
Capacidades de agente (grantedScopes)
Qué puede hacer el asistente adentro de un chat — su dueño le otorga un set de scopes, y una tool sólo aparece si su scope está en ese set.
El PROGRAMA
Scopes de API key
Qué puede llamar en /platform-api un programa de afuera (tu código, un cliente MCP, el dashboard). Tu 403 es casi siempre éste.
La PERSONA
Escalones de audiencia
Qué le muestra el asistente a cada persona que le habla: guest, contact, staff, owner. Por debajo del escalón, una tool directamente no existe para esa persona ese turno.
Lado a lado, por dominio
Generada desde el catálogo en vivo — un dominio que sólo existe de un lado es real, no un agujero de esta tabla.
| Dominio | Capacidad de agente | Scope de API key | En la key por defecto |
|---|---|---|---|
| Agenda sensible | read, write | read, write | — |
| Workspace del agente (notas y archivos) | read, write | — | — |
| API keys sensible | read, write | manage | — |
| Archivos del asistente sensible | — | read, write | — |
| Asistente de alta | — | read, write | sí |
| Asistentes | read, write | read, write | sí |
| Audiencia del asistente sensible | read, write | read, write | — |
| Campañas de mail sensible | read, write, send | read, write | — |
| Canales sensible | read, write | read, write | — |
| Cobros sensible | read, write | read, write | — |
| Consumo | read | read, write | sí |
| Contactos (CRM) | read, write | — | — |
| Derivación a humano sensible | read, write | read, write | — |
| Escalar al workspace | write | — | — |
| Herramientas propias sensible | read, write | read, write | — |
| Imágenes sensible | read, write | write | — |
| Inventario | read, write | read, write | sí |
| Base de conocimiento | read, write | — | — |
| Loops de trabajo | — | read, write | — |
| Memoria del usuario sensible | — | read, write | — |
| Pedidos y checkout | read, write | — | — |
| Preguntas al humano sensible | — | read, write | — |
| Probar el asistente sensible | run | run | — |
| Proyectos | — | read | — |
| Vidriera pública | read, write | — | — |
| Skills | read, write | — | — |
| Squads (multi-agente) | read, write | — | — |
| Tareas | read, write | read, write | — |
| Tareas programadas | read, write | read, write | sí |
| Video (Kondor) sensible | — | read, write, analyze | — |
| Mensajería de WhatsApp | read, write, send | — | — |
| Workflows | read, write | read, write, run | sí |
El detalle completo de cómo otorgar y el modelo acotado al dueño: Capacidades y otorgamiento · API Keys
Qué puede hacer una API key nueva, por defecto
Una key creada sin scopes explícitos recibe exactamente este set — DEFAULT_API_KEY_SCOPES en el backend. Nada más, hasta que se lo otorgues.
assistants:*workflows:*wizard:*usage:readinventory:readinventory:writeschedules:readLos scopes marcados sensibles (chat:run, images:write, tools:*, audience:*, handoff:*, email:*, receivables:*, channels:*, apikeys:manage…) nunca viajan por defecto — cuestan plata, salen de la plataforma, o deciden a quién le contesta tu asistente. Otorgarlos es un acto, no un default.
La key de embed del widget es un set distinto y más chico
La key que viaja adentro del HTML de una página pública (web-widget) no es un secreto — cualquiera que mire el código fuente la puede leer. Por eso lleva sólo esto, a propósito:
assistants:readHasta el 2026-08-29 la key de embed recibía el mismo DEFAULT_API_KEY_SCOPES que una key de servidor, así que una key publicada en el fuente de una página podía reescribir asistentes y escribir inventario de toda la cuenta. Si tenés un build viejo del widget, actualizalo — esto no se arregla con una config, es un fix de código.
Escalones de audiencia: quién está del otro lado del chat
Los escalones se comparan con >=: una regla escrita una vez para staff sigue valiendo cuando aparece un rol nuevo. Un rol como "nutricionista" o "cajera" es dato del asistente — se mapea a uno de estos cuatro escalones.
| Escalón | Significa |
|---|---|
| guest | alguien que no identificamos |
| contact | un contacto conocido, sin verificar |
| staff | alguien del equipo, verificado |
| owner | el dueño de la cuenta |
En un canal que se autentica solo (WhatsApp, Telegram, Facebook, Instagram) el rol declarado de un contacto se toma directo. En el widget web nada se autentica solo — incluso un contacto guardado como owner arranca cada conversación en contact y tiene que canjear un PIN para llegar a staff u owner ese turno.
Tu 403 es uno de estos tres
El error dice qué sistema te frenó. Sólo uno de los tres se arregla editando el asistente: el de scope va en la API key, el de audiencia en el contacto.
"missing scope" / "forbidden" en /platform-apiA tu API KEY le falta ese scope. Mirá la tabla de arriba y otorgáselo a la key (dashboard, o update_api_key si tu key puede administrar keys) — nunca al asistente.
una tool que el asistente debería tener no aparece en el chatEl ASISTENTE no tiene esa capacidad otorgada. grantedScopes vive en la config del asistente, acotado por el rol y el plan de su dueño — otorgá el scope ahí, no en ninguna API key.
el asistente dice que no puede ayudar con eso, a una persona puntualEl escalón de audiencia de esa PERSONA no llega al que pide la tool. Que un guest pregunte algo sólo para staff no es un bug — revisá su escalón, o hacé que canjee un PIN.