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 9 de octubre de 2026. 15 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
La decisión de la persona
Puede desactivar grupos de permisos antes de autorizar.
Si no: el scope cae.

Solo el primer filtro rechaza la solicitud entera; los demás quitan el scope y la autorización sigue.

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: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: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 o editar campos solo se hace desde la aplicación.

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

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
`crm:treasury:reconcile`	Sugerencias de conciliación y exclusión de movimientos
`crm:treasury:export`	Exportar datos de tesorería
`crm:treasury:sync`	Forzar la sincronización bancaria
`crm:fiscal:view`	Ver el calendario fiscal, los modelos y los periodos
`crm:fiscal:calculate`	Calcular modelos tributarios
`crm:fiscal:file`	Marcar modelos como presentados
`crm:fiscal:manage`	Generar, cerrar y reabrir periodos fiscales

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.

Finanzas (finance)

Contabilidad

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 previsión de tesorería, antigüedad de saldos, resumen de IVA y rentabilidad
`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
`finance:commissions:manage`	Gestionar reglas y agentes comisionistas
`finance:commissions:approve`	Aprobar y cancelar comisiones
`finance:commissions:liquidate`	Generar, aprobar y pagar liquidaciones
`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

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

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 y departamentos	CRM
`org:team:manage`	Dar de alta usuarios, cambiar contraseñas y conceder permisos	CRM
`org:observability:view`	Ver el registro de auditoría y las sesiones	CRM
`org:observability:manage`	Cerrar sesiones y purgar el registro de auditoría	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.

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` ni `crm:automations:manage`
`crm:full`	Todos los `crm:` salvo las tres fusiones, 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:`, `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 :read añaden org:notifications:view; los :write y :full, también org:notifications:manage.
Plan: los :write y :full añaden org:plan:request; solo los :full añaden org:plan:manage_requests. Ningún :write da org: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:` y `org:observability:*`
`/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` (se guarda como `/api/mcp`)	Todos los scopes de esta página

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.

Endpoints de scopes

Descripción de scopes (público)

GET

/api/oauth/scopes

Descripción en castellano de los scopes indicados

Recibe los scopes separados por espacios en el parámetro scopes:

Bash

curl -s 'https://os.utilia.ai/api/oauth/scopes?scopes=dev:projects:view%20dev:issues:view'

JSON

[
  { "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)

GET

/api/oauth/user/scopes

Scopes 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.

JSON

{
  "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 responde hasta el 16 de octubre de 2026 con las cabeceras Deprecation y Sunset.

Información pública de un cliente

GET

/api/oauth/clients/:clientId

Dice 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:

JSON

{ "known": true, "isFirstParty": false }

Si el cliente no existe o está desactivado, la respuesta es { "known": false }.

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 9 de octubre de 2026. 15 min de lectura

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
La decisión de la persona
Puede desactivar grupos de permisos antes de autorizar.
Si no: el scope cae.

Solo el primer filtro rechaza la solicitud entera; los demás quitan el scope y la autorización sigue.

Los scopes de identidad (openid, profile, email) pasan siempre.

Cómo se nombran

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

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: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

Las fusiones se piden siempre por su nombre

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

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: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

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

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
`crm:treasury:reconcile`	Sugerencias de conciliación y exclusión de movimientos
`crm:treasury:export`	Exportar datos de tesorería
`crm:treasury:sync`	Forzar la sincronización bancaria
`crm:fiscal:view`	Ver el calendario fiscal, los modelos y los periodos
`crm:fiscal:calculate`	Calcular modelos tributarios
`crm:fiscal:file`	Marcar modelos como presentados
`crm:fiscal:manage`	Generar, cerrar y reabrir periodos fiscales

Finanzas (finance)

Contabilidad

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

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

Informes, cobros, comisiones y ajustes

Scope	Descripción
`finance:reports:view`	Ver previsión de tesorería, antigüedad de saldos, resumen de IVA y rentabilidad
`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
`finance:commissions:manage`	Gestionar reglas y agentes comisionistas
`finance:commissions:approve`	Aprobar y cancelar comisiones
`finance:commissions:liquidate`	Generar, aprobar y pagar liquidaciones
`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

Marketing (marketing)

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

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

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 y departamentos	CRM
`org:team:manage`	Dar de alta usuarios, cambiar contraseñas y conceder permisos	CRM
`org:observability:view`	Ver el registro de auditoría y las sesiones	CRM
`org:observability:manage`	Cerrar sesiones y purgar el registro de auditoría	CRM

La administración de la organización se pide siempre a mano

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` ni `crm:automations:manage`
`crm:full`	Todos los `crm:` salvo las tres fusiones, 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:`, `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 :read añaden org:notifications:view; los :write y :full, también org:notifications:manage.
Plan: los :write y :full añaden org:plan:request; solo los :full añaden org:plan:manage_requests. Ningún :write da org:plan:view.

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:` y `org:observability:*`
`/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` (se guarda como `/api/mcp`)	Todos los scopes de esta página

Si el registro del cliente tiene un recurso por defecto, se aplica aunque no envíes resource.

Endpoints de scopes

Descripción de scopes (público)

GET

/api/oauth/scopes

Descripción en castellano de los scopes indicados

Recibe los scopes separados por espacios en el parámetro scopes:

Bash

curl -s 'https://os.utilia.ai/api/oauth/scopes?scopes=dev:projects:view%20dev:issues:view'

JSON

[
  { "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)

GET

/api/oauth/user/scopes

Scopes 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.

JSON

{
  "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 responde hasta el 16 de octubre de 2026 con las cabeceras Deprecation y Sunset.

Información pública de un cliente

GET

/api/oauth/clients/:clientId

Dice 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:

JSON

{ "known": true, "isFirstParty": false }

Si el cliente no existe o está desactivado, la respuesta es { "known": false }.