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

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](https://os.utilia.ai/docs/developers/oauth/consent-screen) 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**

1. **El cliente** (Registro del cliente): El scope existe y, si el registro limita los permitidos, está en esa lista. Si no: la autorización falla con invalid_scope.
2. **El recurso** (Parámetro resource): Con resource, solo quedan los scopes del servidor MCP indicado (ver Filtrado por recurso, más abajo). Si no: el scope cae.
3. **Los permisos de la persona** (Permisos de UTILIA OS): Cada scope equivale a un permiso de UTILIA OS. Si no: el scope cae.
4. **El plan de la organización** (Aplicativo y capacidad): El aplicativo, y la capacidad dentro de él, tienen que estar contratados. Si no: el scope cae.
5. [**La decisión de la persona**](https://os.utilia.ai/docs/developers/oauth/consent-screen) (Pantalla de consentimiento): 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](#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](https://os.utilia.ai/docs/developers/oauth/oidc-scopes-and-claims).

## 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](https://os.utilia.ai/docs/developers/mcp/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`.

> **Atención: 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](https://os.utilia.ai/docs/developers/mcp/reference#finanzas-servidor-utilia-finance).

## 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](https://os.utilia.ai/docs/developers/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 |

> **Atención: 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 `: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:*`, `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](https://os.utilia.ai/docs/developers/oauth/discovery): 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)

**`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`.

| Nombre | Tipo | Obligatorio | Descripción |
| - | - | - | - |
| `resource` | `string` | No | Servidor MCP, por ejemplo /api/mcp/crm. Recorta a su dominio. |
| `client_id` | `string` | No | 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` 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

**`GET /api/oauth/clients/:clientId`**

Dice si un cliente existe y si es una aplicación propia de UTILIA OS

Parámetro de ruta: `clientId`.

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 }`.