Scopes y recursos
Catálogo de scopes de UTILIA OS, qué incluye cada conjunto y qué scopes puede llevar un token según el servidor MCP al que va atado.
Actualizado el . 20 min de lectura
Un scope es un permiso concreto que tu aplicación pide en nombre de una persona, como crm:clients:view (ver clientes). Esta página es la referencia de todos los que puedes pedir, de los conjuntos que agrupan varios a la vez y de qué scopes admite cada servidor MCP. Pide siempre lo mínimo que necesites: la persona verá cada permiso en la pantalla de consentimiento y es más fácil que autorice una lista corta.
Qué acaba dentro de un token
Lo que pides es el máximo. Cada scope pasa por cinco filtros, en este orden, y el token lleva solo lo que queda:
Filtros de un scope
Registro del cliente
El cliente
El scope existe y, si el registro limita los permitidos, está en esa lista.Si no: la autorización falla con invalid_scope.
Parámetro resource
El recurso
Con resource, solo quedan los scopes del servidor MCP indicado (ver Filtrado por recurso, más abajo).Si no: el scope cae.
Permisos de UTILIA OS
Los permisos de la persona
Cada scope equivale a un permiso de UTILIA OS.Si no: el scope cae.
Aplicativo y capacidad
El plan de la organización
El aplicativo, y la capacidad dentro de él, tienen que estar contratados.Si no: el scope cae.
Pantalla de consentimiento
Puede desactivar grupos de permisos antes de autorizar.Si no: el scope cae.
Los scopes de identidad (openid, profile, email) pasan siempre.
Cómo se nombran
Los scopes tienen la forma dominio:módulo:acción, por ejemplo dev:projects:view. Además hay conjuntos de dos tramos (crm:read, finance:full...) que el servidor expande en scopes individuales: el token guarda los individuales, nunca el nombre del conjunto. Están en Conjuntos.
Identidad (OpenID Connect)
| Scope | Qué da |
|---|---|
openid | El id_token y el identificador de la persona (sub) |
profile | name, given_name, family_name y, si la tiene, picture |
email | email y email_verified |
No dependen de ningún permiso ni del plan. Más detalle en Scopes y claims de OpenID Connect.
Gestión de proyectos (dev)
Proyectos, tareas y sprints
| Scope | Descripción |
|---|---|
dev:projects:view | Ver proyectos |
dev:projects:create | Crear proyectos |
dev:projects:update | Modificar proyectos |
dev:projects:delete | Eliminar proyectos |
dev:issues:view | Ver tareas (issues) |
dev:issues:create | Crear tareas |
dev:issues:update | Modificar tareas (estado, comentarios, tiempo) |
dev:issues:delete | Eliminar tareas |
dev:sprints:view | Ver sprints y su progreso |
dev:sprints:create | Crear sprints |
dev:sprints:update | Modificar sprints |
dev:sprints:delete | Eliminar sprints |
dev:labels:manage | Gestionar etiquetas |
Documentación
| Scope | Descripción |
|---|---|
dev:docs:view | Ver la documentación |
dev:docs:create | Crear documentación |
dev:docs:update | Modificar documentación |
dev:docs:delete | Eliminar documentación |
dev:docs:share | Compartir un documento con enlace público, que cualquiera abre sin iniciar sesión |
dev:docs:share no viaja en ningún conjunto (dev:read, dev:write, dev:full ni admin:full): si tu aplicación comparte documentos, pídelo por su nombre. Desde el 5 de octubre de 2026 es obligatorio para crear enlaces públicos; los tokens anteriores no lo llevan y tienen que volver a autorizarse.
AI Studio
| Scope | Descripción |
|---|---|
dev:ai-studio:view | Ver activos de AI Studio |
dev:ai-studio:manage | Gestionar activos de AI Studio |
dev:prompts:view | Ver prompts |
dev:prompts:create | Crear prompts |
dev:prompts:update | Modificar prompts |
dev:prompts:delete | Eliminar prompts |
Los dev:prompts:* se mantienen por compatibilidad y cubren los activos de tipo prompt.
Gestor de archivos y calendario
| Scope | Descripción |
|---|---|
dev:files:view | Ver archivos y carpetas del gestor de archivos |
dev:files:manage | Crear, mover, renombrar y organizar archivos y carpetas |
dev:files:full | Acceso completo al gestor de archivos, incluido eliminar |
dev:calendar:view | Ver eventos del calendario |
dev:calendar:create | Crear eventos |
dev:calendar:update | Modificar eventos |
dev:calendar:delete | Eliminar eventos |
dev:calendar:invite | Invitar asistentes |
dev:calendar:availability | Ver la disponibilidad de las personas |
Tickets de soporte (support)
| Scope | Descripción |
|---|---|
support:tickets:view | Ver tickets de soporte |
support:tickets:create | Abrir tickets (errores, consultas, sugerencias) |
support:tickets:update | Comentar, resolver y cerrar tickets |
Quien abre el ticket es siempre la persona dueña del token: no se puede abrir en nombre de otra. El contrato de la herramienta está en Herramientas MCP de tickets.
Integraciones (integrations)
Permiten administrar el propio dominio de integraciones de la organización: aplicaciones externas, sus avisos a servidor, métricas y cobros, y las credenciales de API.
| Scope | Descripción |
|---|---|
integrations:apps:view | Ver aplicaciones externas |
integrations:apps:manage | Crear, modificar y eliminar aplicaciones externas |
integrations:apps:webhooks:view | Ver la configuración y las entregas de avisos |
integrations:apps:webhooks:manage | Configurar avisos y reintentar entregas |
integrations:apps:metrics:view | Ver métricas de uso |
integrations:apps:billing:view | Ver la facturación emitida por la aplicación |
integrations:apps:billing:manage | Gestionar la facturación emitida por la aplicación |
integrations:apps:errors:view | Ver los errores que reportan las aplicaciones integradas |
integrations:apps:errors:manage | Resolver, reabrir y silenciar los errores de las aplicaciones integradas, y crear con ellos tickets de soporte o tareas |
integrations:overview:view | Ver el resumen del dominio de integraciones |
integrations:credentials:view | Ver las credenciales de API |
integrations:credentials:manage | Crear, rotar y revocar credenciales de API |
CRM (crm)
Clientes, contactos y leads
| Scope | Descripción |
|---|---|
crm:clients:view | Ver clientes |
crm:clients:view-sensitive | Ver los datos fiscales y económicos de los clientes (NIF, límite de crédito y descuento pactado) |
crm:clients:create | Crear clientes |
crm:clients:update | Modificar clientes |
crm:clients:delete | Eliminar clientes |
crm:clients:merge | Fusionar fichas de cliente duplicadas, sin vuelta atrás |
crm:contacts:view | Ver contactos |
crm:contacts:create | Crear contactos |
crm:contacts:update | Modificar contactos |
crm:contacts:delete | Eliminar contactos |
crm:contacts:merge | Fusionar fichas de contacto duplicadas, sin vuelta atrás |
crm:leads:view | Ver leads |
crm:leads:create | Crear leads |
crm:leads:update | Modificar leads |
crm:leads:delete | Eliminar leads |
crm:leads:convert | Convertir leads en clientes |
crm:leads:merge | Fusionar leads duplicados, sin vuelta atrás |
crm:lead-forms:view | Ver los formularios de captación |
crm:lead-forms:manage | Crear, editar, publicar, pausar, archivar y eliminar formularios de captación |
Hasta el 2 de septiembre de 2026, los datos fiscales y económicos del cliente viajaban con crm:clients:view. Los tokens anteriores a esa fecha los siguen leyendo así hasta el 2 de marzo de 2027; después, hay que autorizar de nuevo pidiendo crm:clients:view-sensitive.
Las fusiones se piden siempre por su nombre
crm:clients:merge, crm:contacts:merge y crm:leads:merge no viajan en ningún conjunto, tampoco en crm:full. Fusionar archiva o elimina fichas y reescribe todo lo que apuntaba a ellas, sin vuelta atrás desde la aplicación: no puede llegarle a una integración por acumulación. Si la tuya fusiona, añade el scope a lo que pides.
Portal del cliente
| Scope | Descripción |
|---|---|
crm:portal:view | Ver quién tiene acceso al portal del cliente: usuarios externos, invitaciones y permisos por empresa |
crm:portal:manage | Invitar y retirar usuarios del portal y cambiar sus permisos y las empresas a las que acceden |
crm:portal:view no entra en crm:read aunque termine en :view, porque son datos de personas ajenas a la organización; crm:portal:manage tampoco entra en crm:write. Se piden por su nombre o con crm:full. Desde el 3 de septiembre de 2026, la herramienta portal_access exige estos scopes y ya no se abre con crm:contacts:update, sin periodo de transición: si tu integración gestiona el acceso al portal, tiene que volver a autorizarse.
Ventas y actividad
| Scope | Descripción |
|---|---|
crm:opportunities:view | Ver oportunidades |
crm:opportunities:create | Crear oportunidades |
crm:opportunities:update | Modificar oportunidades |
crm:opportunities:delete | Eliminar oportunidades |
crm:pipelines:view | Ver etapas y embudos de venta |
crm:custom-fields:view | Ver el catálogo de campos personalizados |
crm:settings:view | Ver la configuración del CRM: etapas del embudo, campos personalizados, motivos de pérdida y puntuación de leads |
crm:settings:manage | Cambiar la configuración del CRM: crear, editar, reordenar y eliminar etapas, campos personalizados y motivos de pérdida, y cambiar la puntuación de leads |
crm:automations:view | Ver las automatizaciones del CRM y sus ejecuciones |
crm:automations:manage | Crear y modificar automatizaciones del CRM |
crm:tasks:view | Ver tareas del CRM |
crm:tasks:create | Crear tareas |
crm:tasks:update | Modificar tareas |
crm:tasks:delete | Eliminar tareas |
crm:interactions:view | Ver interacciones (llamadas, reuniones, notas) |
crm:interactions:create | Registrar interacciones |
crm:interactions:update | Modificar interacciones |
crm:interactions:delete | Eliminar interacciones |
crm:meet:view | Ver reuniones |
crm:meet:create | Crear reuniones |
crm:meet:update | Modificar reuniones |
crm:meet:delete | Eliminar reuniones |
El catálogo de campos personalizados también se lee con el scope de vista de cada entidad (crm:clients:view, crm:contacts:view, crm:leads:view, crm:opportunities:view). Los valores se escriben en el objeto customFields de cada alta o modificación, con el scope de escritura de la entidad. Crear, editar, archivar o eliminar campos, igual que las etapas del embudo, los motivos de pérdida y la puntuación de leads, se hace con la herramienta crm_settings y exige crm:settings:manage. Ese scope no entra en crm:write ni en crm:full: se pide por su nombre. crm:settings:view sí entra en crm:read y en crm:full.
Proyectos, presupuestos, archivos e informes
| Scope | Descripción |
|---|---|
crm:projects:view | Ver proyectos de cliente |
crm:projects:create | Crear proyectos |
crm:projects:update | Modificar proyectos |
crm:projects:delete | Eliminar proyectos |
crm:budgets:view | Ver presupuestos |
crm:budgets:create | Crear presupuestos |
crm:budgets:update | Modificar presupuestos |
crm:budgets:delete | Eliminar presupuestos |
crm:dashboard:view | Ver el panel y las estadísticas del CRM |
crm:files:view | Ver archivos del CRM |
crm:files:upload | Subir archivos al CRM |
crm:files:delete | Eliminar archivos del CRM |
crm:reports:view | Ver informes del CRM |
crm:reports:export | Exportar informes a PDF, Excel o CSV |
Verificar la firma de un presupuesto por MCP (crm_budget_files con verify_signature; la antigua crm_budget_signers está retirada) usa crm:budgets:view, porque solo lee, y exige además que la persona tenga el permiso Verificar firmas de presupuestos. La respuesta da la IP de quien firmó enmascarada; la completa solo está en el certificado PDF, que no se descarga por MCP.
Facturas, tesorería y fiscalidad
| Scope | Descripción |
|---|---|
crm:invoices:view | Ver facturas |
crm:invoices:create | Crear facturas |
crm:invoices:update | Modificar facturas en borrador |
crm:invoices:delete | Eliminar facturas en borrador |
crm:invoices:issue | Emitir facturas |
crm:invoices:cancel | Anular facturas emitidas |
crm:invoices:refund-cancel | Cancelar un reembolso ya emitido |
crm:invoices:export | Exportar y generar el PDF de facturas |
crm:treasury:view | Ver cuentas, saldos, movimientos y previsión de caja (Próximamente) |
crm:treasury:reconcile | Sugerencias de conciliación y exclusión de movimientos (Próximamente) |
crm:treasury:export | Exportar datos de tesorería (Próximamente) |
crm:treasury:sync | Forzar la sincronización bancaria (Próximamente) |
crm:fiscal:view | Ver el calendario fiscal, los modelos y los periodos (Próximamente), y la configuración fiscal y las retenciones |
crm:fiscal:calculate | Calcular modelos tributarios (Próximamente) |
crm:fiscal:file | Marcar modelos como presentados (Próximamente) |
crm:fiscal:manage | Generar, cerrar y reabrir periodos fiscales (Próximamente), y cambiar las retenciones |
Estas herramientas existen en los servidores de CRM (/api/mcp/crm) y de Finanzas (/api/mcp/finance) con los mismos scopes. Conservan el prefijo crm: por compatibilidad, y los conjuntos finance:* los incluyen.
Tesorería e Impuestos están en «Próximamente»: los estamos validando con especialistas antes de ponerlos a tu disposición. Mientras tanto, crm:treasury:* y crm:fiscal:* no dan acceso a esas funciones en tu organización, salvo crm:fiscal:view y crm:fiscal:manage para leer la configuración fiscal y leer o cambiar las retenciones (fiscal: config_get, retention_rates_get y retention_rates_update), que siguen disponibles. El detalle está en la referencia de herramientas MCP.
Finanzas (finance)
Contabilidad
La Contabilidad está en «Próximamente»: mientras tanto, estos scopes no dan acceso a ella en tu organización.
| Scope | Descripción |
|---|---|
finance:accounting:view | Ver plan de cuentas, asientos, libros, balances, activos y ejercicios |
finance:accounting:create | Crear cuentas, asientos, activos y ejercicios |
finance:accounting:update | Modificar cuentas, asientos en borrador, activos y ejercicios |
finance:accounting:delete | Eliminar cuentas, asientos en borrador y activos |
finance:accounting:post | Contabilizar y anular asientos; dotar y revertir amortizaciones; dar de baja activos |
finance:accounting:close | Cerrar y reabrir el ejercicio contable |
finance:accounting:export | Exportar el mayor, las cuentas anuales y la legalización de libros |
Gastos y proveedores
| Scope | Descripción |
|---|---|
finance:expenses:view | Ver gastos, estadísticas y documentos |
finance:expenses:create | Crear gastos |
finance:expenses:update | Modificar, presentar y pagar gastos |
finance:expenses:delete | Eliminar gastos |
finance:expenses:approve | Aprobar y rechazar gastos |
finance:suppliers:view | Ver proveedores y su resumen de gasto |
finance:suppliers:view-sensitive | Ver los datos bancarios y fiscales de los proveedores (NIF, NIF-IVA, IBAN, SWIFT y banco) |
finance:suppliers:create | Crear proveedores |
finance:suppliers:update | Modificar y deduplicar proveedores |
finance:suppliers:delete | Eliminar proveedores |
finance:supplier-contacts:view | Ver las personas de contacto de los proveedores |
finance:supplier-contacts:manage | Crear, modificar y eliminar personas de contacto de los proveedores |
finance:suppliers:interactions:read | Ver la actividad de los proveedores, incluido el contenido de los correos vinculados |
finance:suppliers:interactions:manage | Registrar, editar y eliminar actividad de los proveedores |
Los dos scopes de personas de contacto y los dos de actividad no viajan en finance:read ni en finance:write, aunque uno termine en :view: son datos personales de terceros y contenido de correos, y cederlos exige un consentimiento que se vea. Llegan con finance:full o pidiéndolos por su nombre. Los tokens emitidos antes del 2 de septiembre de 2026 siguen operando sobre las personas de contacto con finance:suppliers:view y finance:suppliers:update hasta el 2 de marzo de 2027; lo mismo ocurre con los datos bancarios y fiscales del proveedor y finance:suppliers:view.
Pagos digitalizados
| Scope | Descripción |
|---|---|
finance:payments:view | Ver pagos digitalizados, registros y duplicados |
finance:payments:create | Subir facturas recibidas para digitalizarlas, sin poder verlas ni modificarlas después |
finance:payments:update | Modificar documentos digitalizados y resolver duplicados |
finance:payments:delete | Eliminar y restaurar pagos |
finance:payments:reprocess | Volver a procesar el documento con IA |
finance:payments:export | Exportar pagos |
Crear un gasto desde un documento (promote_to_expense) exige a la vez finance:payments:view, finance:expenses:create y finance:expenses:approve. Resolver un duplicado conservando los dos (keep_both) exige esos tres y finance:payments:update; descartarlo (discard) exige finance:payments:view, finance:payments:update y finance:payments:delete.
Informes, cobros, comisiones y ajustes
| Scope | Descripción |
|---|---|
finance:reports:view | Ver el resumen de Finanzas. Los demás informes (previsión de tesorería, antigüedad de saldos, resumen de IVA y rentabilidad) están en «Próximamente» |
finance:billing-contacts:view | Ver contactos de facturación |
finance:billing-contacts:manage | Crear, modificar y eliminar contactos de facturación |
finance:payment-methods:view | Ver los métodos de pago guardados |
finance:payment-methods:manage | Añadir, marcar como predeterminado y eliminar métodos de pago |
finance:commissions:view | Ver comisiones, resúmenes y análisis de beneficio (Próximamente) |
finance:commissions:manage | Gestionar reglas y agentes comisionistas (Próximamente) |
finance:commissions:approve | Aprobar y cancelar comisiones (Próximamente) |
finance:commissions:liquidate | Generar, aprobar y pagar liquidaciones (Próximamente) |
finance:einvoicing:generate | Facturae y UBL. La facturación electrónica está retirada desde julio de 2026: el scope sigue existiendo, pero hoy no da acceso a ninguna función |
finance:einvoicing:submit | Presentaciones en FACe. Retirado igual que el anterior: el scope existe, pero hoy no da acceso a ninguna función |
finance:settings:view | Ver la configuración fiscal, de facturación y de régimen |
finance:settings:update | Modificar la configuración de facturación y de régimen |
finance:custom-fields:manage | Crear, editar, reordenar y eliminar los campos personalizados de los proveedores y de sus personas de contacto. Eliminar un campo archivado quita sus valores de todas las fichas |
finance:custom-fields:manage no entra en ningún conjunto, tampoco en finance:full: se pide por su nombre. Leer el catálogo de campos de los proveedores no lo necesita; basta con el scope de ver proveedores o los ajustes.
Marketing (marketing)
Los scopes del servidor de Marketing cubren campañas, listas, plantillas, automatizaciones, exclusiones, informes, entregabilidad, pruebas A/B (marketing:ab-testing), la medición del origen (marketing:tracking:manage) y el detalle por destinatario. El detalle de cada uno, con la herramienta que lo usa, está en Servidor MCP Marketing.
Enviar y programar campañas (marketing:campaigns:send y marketing:campaigns:schedule), las pruebas A/B y la medición del origen no viajan en marketing:write: se piden por su nombre o con marketing:full.
Chat (chat)
| Scope | Descripción |
|---|---|
chat:channels:view | Ver canales del chat interno |
chat:channels:create | Crear canales |
chat:channels:manage | Editar y organizar canales |
chat:members:manage | Gestionar los participantes de un canal |
chat:messages:view | Ver mensajes de los canales |
chat:messages:send | Enviar mensajes en nombre de la persona |
chat:events:subscribe | Suscribirse por aviso a los eventos del chat |
chat:agents:view | Ver los asistentes de IA de los canales |
chat:agents:manage | Gestionar los asistentes de IA de los canales |
chat:agents:manage:external | Gestionar los agentes creados por aplicaciones. No viaja en ningún conjunto |
chat:messages:send, chat:events:subscribe y chat:agents:manage:external son de las aplicaciones externas (API REST y avisos), no del servidor MCP de chat, que no envía mensajes. Por eso su descubrimiento no los anuncia.
RRHH (hr)
| Scope | Descripción |
|---|---|
hr:attendance:view | Ver fichajes, horas y festivos |
hr:attendance:clock | Fichar la jornada propia |
hr:attendance:manage | Administrar horarios, festivos, anomalías y exportaciones |
hr:leave:view | Ver ausencias y vacaciones |
hr:leave:request | Pedir las ausencias propias |
hr:leave:approve | Aprobar o rechazar las ausencias de otras personas |
hr:leave:manage | Ajustar los saldos de vacaciones del equipo |
Formación, scrapers, gamificación y anuncios internos
Estos cuatro módulos no tienen scopes propios. Sus herramientas (training, scraper y workplace, en el servidor CRM) se autorizan con los scopes de CRM o de Gestión de proyectos, y cada operación exige el nivel que corresponde a lo que hace:
| Operación | Scopes que la permiten |
|---|---|
| Consultar: listar, ver el detalle, resultados, clasificaciones, puntos propios | Cualquier crm:*:view o dev:*:view con los que se anuncia la herramienta (los dan crm:read y dev:read) |
| Crear, modificar, publicar, despublicar, lanzar, pausar, reanudar o detener un scraper, ajustar puntos | Un scope de modificación, como crm:clients:update o dev:issues:update (los dan crm:write, dev:write y los :full) |
| Eliminar una formación, un scraper, un grupo de scrapers, una regla de gamificación o un anuncio | Un scope de eliminación, como crm:clients:delete o dev:issues:delete (los dan crm:full y dev:full) |
Un token de solo lectura no puede crear, publicar ni borrar nada en estos módulos. Además, la persona necesita el permiso de UTILIA OS de cada acción (por ejemplo, TRAINING_PUBLISH para publicar una formación), y su organización, el módulo contratado.
El directorio de usuarios (users, en los servidores de Gestión de proyectos y de CRM) es de solo lectura: se consulta con cualquier scope de vista con el que se anuncia en tu servidor o con org:team:view, y la persona necesita además el permiso de ver usuarios.
Transversales de la organización (org)
No pertenecen a un aplicativo: acompañan a los tokens de varios servidores porque sus herramientas están en todos ellos.
| Scope | Descripción | Servidores |
|---|---|---|
org:plan:view | Consultar el plan contratado, los aplicativos y capacidades, el consumo de IA, las peticiones de ampliación y la cita propia con UTILIA (herramienta org_plan) | Todos |
org:plan:request | Pedir una ampliación del plan, seguir y retirar la petición propia, y reservar, cambiar o cancelar una cita con UTILIA | Todos |
org:plan:manage_requests | Cerrar con «Ahora no» las peticiones de ampliación del equipo | Todos |
org:notifications:view | Ver tus avisos y tus preferencias de aviso | Todos |
org:notifications:manage | Marcar avisos como leídos, descartarlos y cambiar tus preferencias de aviso | Todos |
org:email-senders:view | Ver los dominios de envío configurados | CRM y Marketing |
org:email-senders:manage | Configurar y verificar SPF, DKIM y DMARC | CRM y Marketing |
org:settings:view | Ver la configuración de la organización | CRM |
org:settings:update | Modificar la configuración de la organización | CRM |
org:team:view | Ver usuarios, departamentos y los permisos de cada persona, también los de la asesoría | CRM |
org:team:manage | Dar de alta, modificar, activar, desactivar y archivar usuarios, y gestionar los departamentos | CRM |
org:team:permissions:manage | Conceder y retirar permisos a las personas, también al darlas de alta, copiar los de otra persona, crear, cambiar y aplicar plantillas de permisos, y dar, ampliar o devolver el acceso de la asesoría | CRM |
org:team:credentials:manage | Cambiar la contraseña o el correo de acceso de otras personas, reenviarles el correo de alta y consultar el estado de sus enlaces para crear la contraseña (cuándo se generaron, si se usaron y cuándo caducan, nunca el enlace) | CRM |
org:observability:view | Ver sesiones activas, qué contraseñas de aplicación de la unidad de red tiene cada persona (nunca la contraseña), el registro de auditoría y la analítica de uso de IA | CRM |
org:observability:manage | Cerrar sesiones de usuarios, retirar sus contraseñas de aplicación de la unidad de red y depurar el registro de auditoría | CRM |
org:security:view | Ver los ajustes de seguridad de la organización (herramienta org_security_privacy) | CRM |
org:security:manage | Cambiar los ajustes de seguridad de la organización: exigir la verificación en dos pasos, permitir o no el código por correo de reserva, el bloqueo de pantalla, el límite de exportaciones, el modo restringido y los dominios salientes autorizados. Exige tener activada la verificación en dos pasos y cada cambio se confirma en el móvil | CRM |
org:privacy:view | Ver los plazos de conservación, la actividad de los contactos en el portal, las solicitudes de derechos de protección de datos y el registro de incidentes de seguridad | CRM |
org:privacy:manage | Cambiar los plazos de conservación y el registro de la actividad de los contactos en el portal, tramitar las solicitudes de derechos (también la supresión de los datos de una persona) y gestionar los incidentes de seguridad. Exige tener activada la verificación en dos pasos y cada cambio se confirma en el móvil | CRM |
org:privacy:export | Pedir la exportación de todos los datos de la organización. Exige tener activada la verificación en dos pasos y se confirma en el móvil | CRM |
La administración de la organización se pide siempre a mano
Ningún conjunto concede org:team:*, org:observability:* ni org:settings:update. Dar de alta usuarios, conceder permisos, cerrar sesiones o purgar la auditoría exige pedir cada scope por su nombre, y la persona lo verá nombrado al autorizar. Lo único que viaja en crm:read y crm:full es org:settings:view, la lectura de los datos de la organización que el CRM necesita para presupuestos y facturas.
Dar de alta a una persona con permisos (grants en users_create o users_create_many) exige org:team:manage y además org:team:permissions:manage. Hasta el 27 de enero de 2027, un token con org:team:manage puede seguir concediendo permisos y gestionando contraseñas con él; la respuesta incluye entonces un aviso para que vuelvas a autorizar la aplicación con el scope nuevo.
Tampoco ningún conjunto concede org:security:* ni org:privacy:*. Cada escritura de org_security_privacy exige además confirm: true y la confirmación en el móvil, así que la persona necesita tener activada la verificación en dos pasos. Los ajustes de seguridad y la exportación de todos los datos son solo del Super Administrador, y la exportación exige tener la verificación en dos pasos.
Conjuntos
Un conjunto se expande en el servidor a scopes individuales. Pedir dev:read, por ejemplo, da dev:projects:view, dev:issues:view, dev:sprints:view y el resto de lecturas.
| Conjunto | Se expande a |
|---|---|
dev:read | Todos los dev:*:view y org:plan:view |
dev:write | Todos los dev:*:create y dev:*:update, y dev:files:manage |
dev:full | Todos los dev:* salvo dev:docs:share, todos los support:*, todo integrations:* (incluidas las credenciales) y org:plan:view |
support:read | support:tickets:view |
support:write | support:tickets:create y support:tickets:update |
support:full | Los tres support:tickets:* |
crm:read | Todos los crm:*:view salvo crm:portal:view, la lectura del calendario (dev:calendar:view y dev:calendar:availability), org:email-senders:view, org:settings:view y org:plan:view |
crm:write | Todos los crm:*:create y crm:*:update, y crm:files:upload. Sin lecturas: pídelo junto a crm:read. No incluye crm:reports:export, crm:invoices:issue, crm:invoices:export, crm:leads:convert, crm:automations:manage ni crm:settings:manage |
crm:full | Todos los crm:* salvo las tres fusiones y crm:settings:manage, todos los support:*, todos los dev:calendar:*, org:email-senders:*, org:settings:view y org:plan:view |
finance:read | Todos los finance:*:view salvo finance:supplier-contacts:view, crm:invoices:view, crm:treasury:view, crm:fiscal:view y org:plan:view |
finance:write | Todos los finance:*:create y finance:*:update salvo finance:settings:update, crm:invoices:create y crm:invoices:update |
finance:full | Todos los finance:* salvo finance:custom-fields:manage, crm:invoices:*, crm:treasury:*, crm:fiscal:* y org:plan:view |
marketing:read | Todos los marketing:*:view, org:email-senders:view y org:plan:view |
marketing:write | Los marketing:* de crear, modificar y gestionar, salvo el envío, la programación y la medición del origen |
marketing:full | Todos los marketing:*, org:email-senders:* y org:plan:view |
chat:read | chat:channels:view, chat:messages:view, chat:agents:view y org:plan:view |
chat:write | Las tres lecturas, chat:channels:create, chat:channels:manage, chat:members:manage y chat:messages:send |
chat:full | Lo de chat:write, chat:agents:manage, chat:events:subscribe y org:plan:view. Nunca chat:agents:manage:external |
hr:read | hr:attendance:view, hr:leave:view y org:plan:view |
hr:write | Las dos lecturas, hr:attendance:clock y hr:leave:request |
hr:full | Todos los hr:* y org:plan:view |
integrations:full | Todos los integrations:apps:* e integrations:overview:view. Sin las credenciales |
api_credentials:full | integrations:credentials:view e integrations:credentials:manage |
admin:full | Lo mismo que dev:full |
Además, los conjuntos de cada dominio reparten los transversales de esta forma:
- Avisos: los
:readañadenorg:notifications:view; los:writey:full, tambiénorg:notifications:manage. - Plan: los
:writey:fullañadenorg:plan:request; solo los:fullañadenorg:plan:manage_requests. Ningún:writedaorg:plan:view.
finance:write deja fuera a propósito las acciones delicadas: contabilizar, cerrar, aprobar, eliminar, gestionar, reprocesar, exportar, presentar, liquidar y cambiar los ajustes de finanzas. Pídelas por su nombre o con finance:full.
Filtrado por recurso
Cuando la autorización lleva resource, el token solo puede llevar los scopes del servidor indicado. Los de identidad pasan siempre.
| Recurso | Scopes que admite |
|---|---|
/api/mcp/crm | crm:*, support:*, dev:calendar:*, dev:files:*, integrations:credentials:*, finance:suppliers:view, org:email-senders:*, org:settings:*, org:team:*, org:observability:*, org:security:* y org:privacy:* |
/api/mcp/work (se guarda como /api/mcp/dev) | dev:*, support:* e integrations:* |
/api/mcp/finance | finance:*, crm:invoices:*, crm:treasury:*, crm:fiscal:*, crm:clients:view y crm:tasks:view |
/api/mcp/marketing | marketing:*, org:email-senders:* y los crm:*:view. Nunca finance:*, así que por ahí no viajan importes |
/api/mcp/chat | chat:* |
/api/mcp/rrhh | hr:* |
Sin resource | Solo openid, profile y email. Pedir cualquier otro devuelve invalid_request |
Además, todos admiten el plan (org:plan:*) y los avisos (org:notifications:*), y los servidores de Finanzas, Marketing, Chat y RRHH admiten los tres de tickets propios (support:tickets:view, create y update), para que se pueda reportar y seguir lo propio desde cualquiera.
Lo que un servidor admite no es lo mismo que lo que anuncia en su descubrimiento: el documento publica solo lo que sus herramientas usan. El de Chat, por ejemplo, no anuncia chat:messages:send.
Si el registro del cliente tiene un recurso por defecto, se aplica aunque no envíes resource.
La dirección única /api/mcp, que admitía todos los scopes de esta página, se retiró el 20 de octubre de 2026. Ya no se puede pedir como resource ni sirve como recurso por defecto, y sus tokens no abren ningún servidor: conecta cada área por su dirección.
Endpoints de scopes
Descripción de scopes (público)
/api/oauth/scopesDescripción en castellano de los scopes indicados
Recibe los scopes separados por espacios en el parámetro scopes:
curl -s 'https://os.utilia.ai/api/oauth/scopes?scopes=dev:projects:view%20dev:issues:view'[
{ "scope": "dev:projects:view", "description": "Ver proyectos de desarrollo" },
{ "scope": "dev:issues:view", "description": "Ver issues y tareas" }
]Scopes que puede conceder la persona (sesión de UTILIA OS)
/api/oauth/user/scopesScopes que la persona con sesión puede autorizar
Lo usa la pantalla de consentimiento con la sesión de la persona. Devuelve los scopes recortados por sus permisos, por el plan de su organización y, si lo indicas, por resource.
- resourcestring
- Servidor MCP, por ejemplo /api/mcp/crm. Recorta a su dominio.
- client_idstring
- Si lo indicas, la respuesta añade client con { isFirstParty } cuando el cliente existe y está activo.
{
"scopes": ["openid", "profile", "email", "crm:clients:view", "crm:leads:view"],
"descriptions": [
{ "scope": "crm:clients:view", "description": "Ver clientes del CRM" }
],
"client": { "isFirstParty": false }
}El endpoint antiguo GET /api/oauth/user-scopes sigue respondiendo con las cabeceras Deprecation y Sunset, pero su fecha de retirada (16 de octubre de 2026) ya pasó: cámbialo por GET /api/oauth/user/scopes, porque puede dejar de responder en cualquier momento.
Información pública de un cliente
/api/oauth/clients/:clientIdDice si un cliente existe y si es una aplicación propia de UTILIA OS
Público, con un límite de 30 peticiones por minuto. Responde siempre 200 con la misma forma, para que nadie pueda enumerar clientes:
{ "known": true, "isFirstParty": false }Si el cliente no existe o está desactivado, la respuesta es { "known": false }.