Permisos de la API (scopes)
Cómo conceder y retirar permisos a una aplicación externa: los 61 permisos, sus tipos, los 17 que solo concede un Super Administrador, el recorte por plan y la auditoría.
Actualizado el . 21 min de lectura
Incluido en todos los planes. Ver precios
Los permisos de la API (scopes) deciden qué datos puede leer y qué
acciones puede hacer una aplicación externa cuando llama a la API con
su X-Api-Key. Esta página explica cómo se conceden desde el panel, qué
reglas de seguridad y de datos personales se aplican, y cómo
automatizarlo por MCP.
Antes de empezar
Para cambiar los permisos de una aplicación necesitas el permiso «Editar aplicaciones externas». Para ampliar los permisos tienes que ser la persona responsable de la aplicación o Super Administrador, y para añadir cualquiera de los 17 permisos protegidos (datos personales críticos, dinero o agentes de IA), Super Administrador, con un motivo.
Dónde se configuran
En la ficha de tu aplicación, en Configuración, Ajustes, pestaña Permisos, está la tarjeta Permisos de la API con todos los permisos disponibles. La ficha se abre desde Ajustes, Creadas por tu empresa. Cada uno lleva su nombre, una descripción corta y, si procede, un distintivo de dato sensible o de acción protegida.
La tarjeta se alimenta del catálogo del servidor, que es la única fuente de verdad: los textos y distintivos se calculan allí. Si la clave de la aplicación está publicada en páginas web, los permisos que no se pueden usar con ella salen apagados, con el motivo: «Solo en una aplicación sin dominios autorizados» (Claves dentro de una página web).
Catálogo de permisos
El catálogo tiene 61 permisos en quince áreas: contactos, leads, clientes, usuarios externos, facturación, cobros con tarjeta, suscripciones, autorizaciones de cobro, cobros programados, soporte, archivos, presupuestos, analítica, chat e instalaciones del catálogo. Las tablas indican el tipo de operación, los endpoints que lo exigen y si solo puede concederlo un Super Administrador. El recuento y su desglose están en Catálogo de permisos de la API.
Cada permiso declara además qué aplicativos y capacidades del plan necesita para servir de algo, y el catálogo se recorta con esa declaración: los que tu plan no cubre aparecen con candado y no se pueden conceder. Ver El catálogo se recorta por el plan.
Dominio CRM · Contactos (6)
| Permiso | Tipo | Descripción | Endpoint(s) | ¿Solo Super Administrador? |
|---|---|---|---|---|
crm:contacts:read | Lectura básica | Listar, buscar y ver el detalle de contactos del CRM. | GET /external/v1/contacts, /:id, /search, /by-email, /sync | No |
crm:contacts:write | Escritura | Registrar bajas y reactivaciones, estas con prueba del consentimiento. | POST /external/v1/contacts/:id/unsubscribe, /resubscribe | No |
crm:contacts:read:secondary-email | Sensible | Segundo correo del contacto, cuando pides ?include=secondaryEmail. | GET /external/v1/contacts con include | No |
crm:contacts:read:birthday | Sensible | Día y mes de nacimiento del contacto. | GET /external/v1/contacts con ?include=birthday | No |
crm:contacts:read:notes | Datos personales críticos | Notas privadas del equipo sobre el contacto. Datos cualitativos sensibles. | GET /external/v1/contacts con ?include=notes | Sí |
crm:contacts:read:opted-out | Datos personales críticos | Acceso a contactos que ejercieron su derecho de oposición (baja). | GET /external/v1/contacts (listado completo) | Sí |
Dominio CRM · Leads (5)
| Permiso | Tipo | Descripción | Endpoint(s) | ¿Solo Super Administrador? |
|---|---|---|---|---|
crm:leads:read | Lectura básica | Listar y ver leads (nombre, empresa, correo, estado, etapa, prioridad y origen). | GET /external/v1/leads | No |
crm:leads:read:scoring | Sensible | Puntuación y temperatura del lead (score, temperature). | GET /external/v1/leads con ?include=scoring | No |
crm:leads:write | Escritura | Crear leads, cualificar (QUALIFIED), descartar (LOST), actualizar y ajustar el scoring. No elimina ni convierte. | POST /external/v1/leads, /:id/qualify, /:id/disqualify, /:id/score, PATCH /:id | No |
crm:leads:convert | Datos personales críticos | Convertir un lead en contacto del CRM y opcionalmente en oportunidad. Crea entidades nuevas. | POST /external/v1/leads/:id/convert | Sí |
crm:leads:read:notes | Datos personales críticos | Notas privadas del equipo sobre el lead. | GET /external/v1/leads con ?include=notes | Sí |
Dominio CRM · Clientes (5)
| Permiso | Tipo | Descripción | Endpoint(s) | ¿Solo Super Administrador? |
|---|---|---|---|---|
crm:clients:read | Lectura básica | Listar y ver clientes (nombre comercial, sector, estado), incluido su grupo de empresas. Sin él, primaryClient no sale en los contactos. | GET /external/v1/clients, /:id/group | No |
crm:clients:write | Escritura | Crear clientes, actualizar la ficha, desactivar (status=INACTIVE) y reactivar. No elimina ni cambia el vínculo de grupo. | POST /external/v1/clients, PATCH /:id, POST /:id/deactivate, /:id/reactivate | No |
crm:clients:write:hierarchy | Sensible | Vincular y desvincular filiales de su empresa matriz (parentClientId). Se exige además de crm:clients:write porque reorganizar el grupo cambia las vistas consolidadas y permite facturar a la matriz un presupuesto de la filial. | PATCH /external/v1/clients/:id con parentClientId | No |
crm:clients:read:fiscal-data | Datos personales críticos | NIF o CIF, dirección fiscal, régimen y retenciones. Para autónomos es dato personal identificativo. | GET /external/v1/clients/:id, /by-tax-id con ?include=fiscalData | Sí |
crm:clients:read:notes | Datos personales críticos | Notas privadas del equipo sobre el cliente. | GET /external/v1/clients/:id con ?include=notes | Sí |
Dominio CRM · Usuarios externos (3)
| Permiso | Tipo | Descripción | Endpoint(s) | ¿Solo Super Administrador? |
|---|---|---|---|---|
crm:users:read | Lectura básica | Consultar el listado de usuarios externos vinculados a la aplicación, sin su NIF ni su dirección de facturación. Con una clave que no está publicada en páginas web, también lo guardado del usuario en la respuesta de identify. | GET /external/v1/users | No |
crm:users:write | Escritura | Dar de alta y actualizar los usuarios finales de la aplicación, con su correo, su NIF y su dirección de facturación, y vincularlos a una ficha de cliente del CRM. | POST /external/v1/users/identify | No |
crm:users:read:fiscal-data | Datos personales críticos | Leer el NIF y la dirección de facturación guardados de los usuarios. Sin él, el listado no los trae e identify solo devuelve los que mandas en esa llamada. Para un autónomo, el NIF lo identifica. | GET /external/v1/users, POST /external/v1/users/identify | Sí |
Dominio Facturación (6)
| Permiso | Tipo | Descripción | Endpoint(s) | ¿Solo Super Administrador? |
|---|---|---|---|---|
crm:invoices:read | Lectura básica | Listar facturas, ver el detalle, descargar el PDF, consultar estadísticas, leer el enlace público vigente y consultar las series de facturación en las que la aplicación puede numerar. Si la organización tiene disponible la ventanilla única del IVA (hoy, «Próximamente»), también los tipos de IVA vigentes de los Estados miembros de la Unión. Las series las crea y configura la organización; la aplicación solo elige entre las suyas. | GET /external/v1/invoices, /:id, /:id/pdf, /stats, /series, /eu-vat-rates, /:id/public-link | No |
crm:invoices:write | Escritura | Crear facturas en nombre del usuario externo, registrar cobros fuera de la pasarela y emitir el enlace público. Por sí solo no basta para crear: POST /external/v1/invoices exige además crm:invoices:issue. No permite cancelar ni modificar facturas ya emitidas. | POST /external/v1/invoices, /:id/mark-paid, /:id/public-link | No |
crm:invoices:send | Escritura | Enviar al usuario final la factura por correo con su PDF, usando la plantilla y el remitente de la organización. Se concede aparte de la creación: facturar y escribir al cliente son cosas distintas. | POST /external/v1/invoices/:id/send | No |
crm:invoices:issue | Sensible | Junto con crm:invoices:write, permite que POST /external/v1/invoices numere y emita la factura en el mismo paso. Se exige desde la primera llamada: sin él, la creación responde 403. | POST /external/v1/invoices | No |
crm:invoices:cancel | Crítico financiero | Anular facturas emitidas. Solo se revierte emitiendo una rectificativa. | POST /external/v1/invoices/:id/cancel | Sí |
crm:invoices:rectify | Crítico financiero | Emitir una rectificativa de una factura que emitió la propia aplicación, por devolución o por un contracargo que deja la venta sin efecto. UTILIA OS decide el código legal (R5 o R1) y resta con importes negativos. Registrar a la vez la devolución hecha en tu pasarela exige además crm:invoices:write, y enviarla por correo, crm:invoices:send. No mueve dinero. Una rectificativa emitida no se puede retirar. | POST /external/v1/invoices/:id/rectifications | Sí |
Dominio Cobros con tarjeta (4)
| Permiso | Tipo | Descripción | Endpoint(s) | ¿Solo Super Administrador? |
|---|---|---|---|---|
billing:payment-methods:read | Lectura básica | Listar las tarjetas guardadas del usuario externo y consultar el historial de intentos de cobro de una factura. | GET /external/v1/payment-methods, GET /external/v1/invoices/:id/payment-intents | No |
billing:payment-methods:write | Escritura | Crear el SetupIntent con el que guardar una tarjeta, marcar una como predeterminada y desvincularla. | POST /external/v1/payment-methods/setup-intent, /payment-methods/:pmId/set-default, DELETE /payment-methods/:pmId | No |
billing:charge | Crítico financiero | Cobrar una factura, con el usuario delante o sin él. Mueve dinero real desde la tarjeta guardada del cliente. | POST /external/v1/invoices/:id/pay, /:id/charge | Sí |
billing:refund | Crítico financiero | Devolver, entero o en parte, el dinero ya cobrado de una factura. | POST /external/v1/invoices/:id/refund | Sí |
Dominio Suscripciones (3)
Exigen el aplicativo Finanzas y la capacidad de facturación recurrente.
| Permiso | Tipo | Descripción | Endpoint(s) | ¿Solo Super Administrador? |
|---|---|---|---|---|
billing:subscriptions:read | Lectura básica | Consultar las suscripciones de los usuarios de la aplicación: estado, importe por periodo, próxima factura, historial y facturas generadas. | GET /external/v1/subscriptions y sus subrutas de lectura | No |
billing:subscriptions:write | Escritura | Dar de alta suscripciones, modificarlas, pausarlas, reanudarlas, reactivarlas y adelantar la generación de una factura. Si la suscripción cobra sola, adelantar la factura adelanta también el cobro y pide además billing:scheduled-charges:write o billing:charge. Reintentar el cobro de una cuota no va con este permiso: es de billing:scheduled-charges:write. | POST /external/v1/subscriptions, PATCH /:id, /:id/pause, /:id/resume, /:id/reactivate, /:id/generate-now | No |
billing:subscriptions:cancel | Crítico financiero | Dar de baja definitivamente una suscripción. Corta un ingreso recurrente y no se deshace. | POST /external/v1/subscriptions/:id/cancel | Sí |
Dominio Autorizaciones de cobro (3)
Exigen los aplicativos Finanzas y Stripe y la capacidad de cobro automático.
| Permiso | Tipo | Descripción | Endpoint(s) | ¿Solo Super Administrador? |
|---|---|---|---|---|
billing:payment-authorizations:read | Lectura básica | Consultar qué usuarios han autorizado el cobro automático, con qué alcance y sobre qué tarjeta, y pedir el texto de consentimiento vigente. | GET /external/v1/payment-authorizations, /:id, /consent-text | No |
billing:payment-authorizations:write | Crítico financiero | Registrar la autorización que el usuario acaba de firmar en la aplicación, con el texto, la fecha, la dirección IP y el navegador. Es la prueba legal que habilita cobrar sin nadie delante. | POST /external/v1/payment-authorizations | Sí |
billing:payment-authorizations:revoke | Escritura | Retirar una autorización. La retirada es inmediata y arrastra los cobros programados y el cobro automático de las suscripciones. | POST /external/v1/payment-authorizations/:id/revoke | No |
Dominio Cobros programados (2)
Exigen los aplicativos Finanzas y Stripe y la capacidad de cobro automático.
| Permiso | Tipo | Descripción | Endpoint(s) | ¿Solo Super Administrador? |
|---|---|---|---|---|
billing:scheduled-charges:read | Lectura básica | Consultar los cobros programados de las facturas: cuándo se ejecutarán, cuántos intentos llevan y por qué falló el último. | GET /external/v1/invoices/:id/scheduled-charges | No |
billing:scheduled-charges:write | Crítico financiero | Programar el cobro de una factura para una fecha futura, cancelarlo mientras la ventana siga abierta, adelantar un reintento, que cobra en el momento, y reintentar ya el cobro de una cuota de suscripción que no se pudo cobrar (que pide además la facturación recurrente). No sustituye a la autorización del usuario. | POST /external/v1/invoices/:id/scheduled-charges, DELETE /external/v1/scheduled-charges/:id, POST /scheduled-charges/:id/retry-now, POST /subscriptions/:id/invoices/:invoiceId/retry-charge | Sí |
Dominio Soporte · Tickets (3)
| Permiso | Tipo | Descripción | Endpoint(s) | ¿Solo Super Administrador? |
|---|---|---|---|---|
support:tickets:read | Lectura básica | Listar tickets, ver el detalle, consultar los mensajes sin leer y recibir los cambios por SSE. | GET /external/v1/tickets, /:id, /unread-count, /events | No |
support:tickets:write | Escritura | Crear tickets, añadir mensajes, cerrarlos y reabrirlos en nombre del usuario externo. | POST /external/v1/tickets, /:id/messages, PATCH /:id/close, /:id/reopen | No |
support:tickets:ai | Datos personales críticos | Pedir sugerencias con IA para el ticket y transcribir audio. Consume cuota de IA y envía datos personales a un proveedor externo. | POST /external/v1/tickets/ai-suggest, /ai-track-action, /ai-transcribe, /ai-transcribe-async y sus consultas de estado | Sí |
Dominio Archivos (2)
| Permiso | Tipo | Descripción | Endpoint(s) | ¿Solo Super Administrador? |
|---|---|---|---|---|
fm:files:read | Lectura básica | Consultar la cuota y obtener direcciones firmadas para descargar los archivos subidos por la aplicación. | GET /external/v1/files/quota, /:id/url | No |
fm:files:write | Escritura | Subir archivos desde la aplicación externa. | POST /external/v1/files/upload | No |
Dominio Presupuestos (4)
| Permiso | Tipo | Descripción | Endpoint(s) | ¿Solo Super Administrador? |
|---|---|---|---|---|
crm:budgets:comments:read | Lectura básica | Listar los comentarios CLIENT del presupuesto (los que ve el cliente en el portal). | GET /external/v1/budgets/:budgetId/comments | No |
crm:budgets:comments:write | Escritura | Crear comentarios CLIENT en el presupuesto. Las menciones se ignoran. | POST /external/v1/budgets/:budgetId/comments | No |
crm:budgets:signatures:read | Lectura básica | Listar las firmas y ver su detalle (con la IP parcialmente oculta). | GET /external/v1/budgets/:budgetId/signatures, /:sigId | No |
crm:budgets:signatures:verify | Datos personales críticos | Recalcular la huella del documento firmado y compararla con la guardada. En malas manos, permitiría comprobar si una manipulación pasa desapercibida. | GET /external/v1/budgets/:budgetId/signatures/:sigId/verify | Sí |
Verificar firmas tiene permiso propio en la API externa y no en OAuth por una razón de fondo: detrás de una clave de API no hay ninguna persona, así que su permiso es la única puerta. Un token OAuth siempre actúa con los permisos de quien lo autorizó, y para verificar por MCP esa persona necesita además el permiso Verificar firmas de presupuestos; por eso allí basta crm:budgets:view (Scopes y recursos).
Dominio Analítica de IA (1)
| Permiso | Tipo | Descripción | Endpoint(s) | ¿Solo Super Administrador? |
|---|---|---|---|---|
analytics:ai:read | Lectura básica | Consultar el resumen y la evolución del uso de IA de la propia aplicación. | GET /external/v1/ai-analytics/overview, /trends | No |
Dominio Errores de la aplicación (3)
| Permiso | Tipo | Descripción | Endpoint(s) | ¿Solo Super Administrador? |
|---|---|---|---|---|
analytics:errors:read | Lectura básica | «Leer errores reportados»: listar los errores que ha enviado la aplicación, ver el detalle de cada uno y consultar sus estadísticas. | GET /external/v1/errors, /stats, /:hash | No |
analytics:errors:write | Escritura | «Reportar errores al backend»: enviar los errores de la aplicación, uno a uno, en lotes o desde el widget. Los iguales se agrupan. | POST /external/v1/errors/report, /batch, POST /external/v1/tickets/client-errors | No |
analytics:errors:manage | Escritura | «Gestionar errores reportados»: resolver, reabrir y silenciar los errores que ha enviado la propia aplicación. Actúa en nombre de su persona responsable, que necesita el permiso de gestionar los errores de las aplicaciones externas. | POST /external/v1/errors/:hash/resolve, /reopen, /silence, DELETE /:hash/silence | No |
Dominio Chat (9)
| Permiso | Tipo | Descripción | Endpoint(s) | ¿Solo Super Administrador? |
|---|---|---|---|---|
chat:messages:send | Escritura | Publicar mensajes como la aplicación en un canal concedido. Aparece como autor propio, nunca en nombre de una persona. | POST /external/v1/chat/channels/:channelId/messages | No |
chat:channels:view | Lectura básica | Listar los canales concedidos, su detalle y sus miembros. | GET /external/v1/chat/channels, /:channelId, /:channelId/members | No |
chat:messages:view | Lectura básica | Leer los mensajes de un canal concedido. Solo mensajes públicos y dirigidos a los participantes; nunca internos del equipo, privados ni respuestas privadas de la IA. | GET /external/v1/chat/channels/:channelId/messages, /messages/:messageId | No |
chat:events:subscribe | Lectura básica | Recibir los avisos de los canales concedidos donde participa la aplicación. | Entrega saliente (no tiene endpoint propio) | No |
chat:channels:create | Escritura | Crear canales como la aplicación, dentro de los permisos de quien concedió el acceso. | POST /external/v1/chat/channels | No |
chat:channels:manage | Escritura | Editar y archivar canales concedidos. Borrarlos exige además su permiso propio. | PATCH /external/v1/chat/channels/:channelId, POST /:channelId/archive | No |
chat:members:manage | Escritura | Añadir y retirar miembros de un canal concedido. Retirar exige además el permiso correspondiente. | POST /external/v1/chat/channels/:channelId/members, DELETE /:channelId/members/:userId | No |
chat:agents:view | Lectura básica | Listar los agentes de IA que la propia aplicación ha creado en los canales concedidos y ver su estado. | GET /external/v1/chat/channels/:channelId/agents | No |
chat:agents:manage:external | Escritura | Crear y configurar agentes de IA de canal que actúan con los permisos prestados de una persona. La capacidad más protegida del catálogo. | POST /external/v1/chat/channels/:channelId/agents, PATCH y DELETE /external/v1/chat/channels/:channelId/agents/:agentId, más /pause y /resume | Sí |
En el chat hay dos puertas: el permiso autoriza la acción y el acceso a
cada canal lo concede aparte una persona responsable de ese canal. Con
chat:messages:send no basta para escribir en un canal al que la aplicación
no ha sido invitada. Al conceder cualquier chat:*, la aplicación queda
habilitada en el chat, pero no ve ningún canal hasta que alguien se lo
conceda. Más en Scopes y acceso por canal.
Dominio Instalaciones del catálogo (2)
Son de la aplicación que publica una ficha en el catálogo de aplicaciones, sobre sus propias instalaciones. Nunca se piden a una empresa que la instala. Ver Referencia de las instalaciones.
| Permiso | Tipo | Descripción | Endpoint(s) | ¿Solo Super Administrador? |
|---|---|---|---|---|
apps:installations:read | Lectura básica | Ver las empresas que han instalado las fichas de la aplicación, con su estado, los permisos que concedieron y, si es de pago, su suscripción. | GET /external/v1/app-installations, /:id | No |
apps:installations:exchange | Escritura | Canjear el código de un solo uso de cada instalación por su clave de API y su clave de firma. Solo desde un servidor. | POST /external/v1/app-installations/exchange | No |
Los cinco tipos
- Lectura básica (
basic, 20 permisos): lo imprescindible para que la aplicación funcione. Sin distintivo. - Escritura (
write, 20 permisos): cambios reversibles en el CRM, las facturas, las tarjetas, los archivos, los tickets, el chat o el registro de errores. - Sensible (
sensitive, 5 permisos): datos personales o comerciales adicionales y acciones de más alcance del que aparentan, sin llegar a críticos. - Datos personales críticos (
rgpd-critical, 9 permisos): notas internas, contactos dados de baja, datos fiscales de clientes y de usuarios, conversión de leads, verificación de firmas y procesado de tickets con IA. - Crítico financiero (
financial-critical, 7 permisos): mueve dinero, corta un ingreso o resta ingresos con un documento fiscal. Se concede con las mismas exigencias que el tipo anterior; el tipo distinto dice a quien revisa la solicitud por qué está protegido.
Los 17 permisos que solo concede un Super Administrador
Solo puede añadirlos un Super Administrador, con un motivo de al menos veinte caracteres. Retirarlos no exige nada especial.
- Datos personales críticos:
crm:contacts:read:notes,crm:contacts:read:opted-out,crm:leads:convert,crm:leads:read:notes,crm:clients:read:fiscal-data,crm:clients:read:notes,crm:users:read:fiscal-data,support:tickets:aiycrm:budgets:signatures:verify. - Críticos financieros:
crm:invoices:cancel,crm:invoices:rectify,billing:charge,billing:refund,billing:subscriptions:cancel,billing:payment-authorizations:writeybilling:scheduled-charges:write. - Agentes de IA:
chat:agents:manage:external, de tipo escritura pero el más protegido del catálogo: permite crear agentes de IA que actúan con los permisos prestados de una persona, no entra en ningún paquete y cada agente creado espera la firma en persona de un responsable del canal (Gestionar agentes de IA).
Paquetes sugeridos
La tarjeta ofrece atajos para los casos más comunes. Elegir uno marca sus permisos y te deja afinar el resto.
| Paquete | Para qué | Permisos que marca |
|---|---|---|
| Herramienta de envío de correos | Sincronizar listas y respetar las bajas | crm:contacts:read, crm:contacts:read:opted-out |
| Plataforma de prospección | Leer y registrar contactos, leads y empresas | crm:contacts:read, crm:contacts:write, crm:clients:read, crm:leads:read, crm:leads:write |
| Tickets y soporte | Dar de alta a los usuarios y dejar que abran y sigan sus tickets | crm:users:read, crm:users:write, support:tickets:read, support:tickets:write |
| Sincronización CRM | Sincronizar contactos, leads y clientes, sin notas internas ni conversión | crm:contacts:read, crm:contacts:read:secondary-email, crm:contacts:read:birthday, crm:contacts:write, crm:clients:read, crm:clients:write, crm:leads:read, crm:leads:read:scoring, crm:leads:write |
| Facturación y cobros | Dar de alta a los usuarios, facturarles, guardar su tarjeta y cobrarles, también cuotas | crm:users:read, crm:users:write, crm:invoices:read, crm:invoices:write, crm:invoices:issue, crm:invoices:send, billing:payment-methods:read, billing:payment-methods:write, billing:charge, billing:subscriptions:read, billing:subscriptions:write, billing:payment-authorizations:read, billing:payment-authorizations:write, billing:scheduled-charges:read, billing:scheduled-charges:write |
| Aplicación de chat | Leer y escribir en los canales y recibir sus avisos | chat:channels:view, chat:messages:view, chat:messages:send, chat:events:subscribe |
| Personalizado | Elegir uno a uno | Ninguno |
Anular facturas, emitir rectificativas, devolver dinero y dar de baja
suscripciones no entran en ningún paquete: se conceden a mano, uno a
uno. El paquete de facturación sí marca billing:charge,
billing:payment-authorizations:write y billing:scheduled-charges:write,
así que guardarlo exige ser Super Administrador y escribir un motivo.
Conceder o retirar permisos
Abre la aplicación
En Ajustes, Creadas por tu empresa, abre la aplicación y entra en Configuración › Ajustes, pestaña Permisos.
Busca los permisos
La tarjeta Permisos de la API muestra todos los permisos con su estado actual, agrupados por área. Bajo cada uno aparece su nombre técnico (por ejemplo,
crm:invoices:write) para encontrarlo rápido.Marca o desmarca
Pulsa para añadir o quitar. La tarjeta muestra antes de guardar qué permisos vas a añadir y cuáles vas a quitar.
Escribe el motivo si añades uno protegido
Si añades alguno de los 17 permisos protegidos, la tarjeta pide un motivo de al menos 20 caracteres. Sin él, no se puede guardar (y la API respondería
422 REASON_REQUIRED_FOR_RGPD_SCOPE).Guarda
Pulsa Guardar. El servidor comprueba tus permisos, comprueba que nadie haya cambiado la aplicación mientras tanto y aplica el cambio. Un mensaje confirma exactamente qué se ha cambiado. El cambio vale desde la siguiente llamada: no hace falta rotar la clave de API ni reiniciar la aplicación.
Si tu aplicación recibe un 403 INSUFFICIENT_SCOPE
Significa que a tu aplicación le falta un permiso de la API, y la
respuesta dice cuál: requiredScopes trae la lista de los que faltan
y el mensaje, su nombre en el catálogo y dónde se concede. Solo habla
de tu propia aplicación: nada de otras aplicaciones, de otras
organizaciones ni de la persona responsable.
{
"statusCode": 403,
"message": "A esta aplicación le falta el permiso de la API «Emitir facturas» (crm:invoices:issue) para esta operación. Lo concede un administrador de la organización en UTILIA OS, en la ficha de la aplicación, Configuración › Ajustes › Permisos.",
"error": "FORBIDDEN",
"errorCode": "INSUFFICIENT_SCOPE",
"requiredScopes": ["crm:invoices:issue"],
"fixedBy": "organization",
"docsUrl": "https://os.utilia.ai/docs/developers/getting-started/errors-and-retries#insufficient_scope",
"retryable": false,
"timestamp": "2026-10-21T10:15:32.114Z",
"requestId": "550e8400-e29b-41d4-a716-446655440000"
}Como todo error de la API externa, trae además fixedBy (aquí,
organization: lo arregla un administrador), docsUrl, la dirección del
apartado de INSUFFICIENT_SCOPE
en la documentación pública, y retryable (aquí, false: repetirla no
cambiará nada hasta que se conceda el permiso). Decide con errorCode y lee
requiredScopes; no analices el texto del mensaje, que puede cambiar.
No hay periodo de gracia: el permiso se exige en todas las llamadas desde la primera, también en aplicaciones antiguas. La tolerancia que acompañó al despliegue del 25 de mayo de 2026 ya no existe.
Para pedir el permiso:
- Mira qué permiso falta en
requiredScopes. Para saberlo antes de llamar,POST /external/v1/diagnostics/check-requestcomprueba la petición sin ejecutarla, yGET /external/v1/diagnosticslista lo que tu clave puede llamar y lo que no (ver Probar tu integración). Una ruta puede exigir más de uno: crear una factura conPOST /external/v1/invoicespidecrm:invoices:writeycrm:invoices:issue. - Pídeselo al administrador de la organización con el nombre exacto (por ejemplo,
crm:invoices:write) y para qué lo necesitas. Si es uno de los 17 protegidos, prepara también un motivo de al menos 20 caracteres. - El administrador lo concede en la tarjeta Permisos de la API. La siguiente llamada ya responde
200.
Reglas de seguridad
Cambiar los permisos, desde la ficha o por MCP, envía la lista completa de permisos que debe tener la aplicación. Antes de guardarla, el servidor hace estas comprobaciones, en este orden:
Qué comprueba el servidor al cambiar los permisos
¿Están en el catálogo y la aplicación activa?
Si no: 400 INVALID_SCOPE o 409 EXTERNAL_APP_REVOKED.
¿Nadie la ha cambiado antes?
Solo si envías expectedUpdatedAt con la versión que estabas viendo.Si no: 409 EXTERNAL_APP_SCOPES_CONFLICT. Recarga y repite.
¿Los cubre el plan?
Si no: 400 SCOPE_OUT_OF_PLAN.
¿Caben en una clave publicada?
Solo si la clave está publicada en páginas web.Si no: 400 SCOPE_NOT_ALLOWED_WITH_ALLOWED_ORIGINS.
¿Puedes ampliarlos?
Solo la persona responsable o un Super Administrador.Si no: 403 RESPONSIBLE_SELF_ONLY.
¿Puedes añadir los protegidos?
Hace falta ser Super Administrador y un motivo de 20 caracteres o más.Si no: 403 SUPER_ADMIN_REQUIRED_FOR_RGPD_SCOPE o 422 REASON_REQUIRED_FOR_RGPD_SCOPE.
Si todo pasa, el servidor guarda el cambio, calcula qué se añade y qué
se quita, y lo deja en el registro de auditoría. Si mientras tanto
alguien ha cambiado los permisos o los dominios de la aplicación, la
respuesta es 409 y no se guarda nada.
- Los tokens OAuth se revocan: al retirar un permiso, los tokens OAuth activos que lo incluían dejan de valer y la aplicación tiene que volver a pedir consentimiento. La clave de API y el secreto de los avisos no se rotan.
- Cambio en tiempo real: quien tenga la aplicación abierta ve el cambio sin recargar.
- Sin datos internos: la respuesta
INSUFFICIENT_SCOPEnombra el permiso que falta, pero nunca direcciones del panel ni identificadores internos.
El catálogo se recorta por el plan
Conceder un permiso no basta: tu organización tiene que tener en su
plan el aplicativo, y en su caso la capacidad, que ese permiso
gobierna. Son dos puertas distintas, y las dos se comprueban en el
servidor. Cada permiso declara sus requiredModules y
requiredCapabilities, y con eso:
- Se marca el catálogo que ve el panel: los permisos que tu plan no cubre llegan con
outOfPlan: truey se muestran con candado, sin poder concederse. - Se rechaza conceder un permiso fuera de plan, con
400 SCOPE_OUT_OF_PLAN. - El endpoint responde
403antes incluso de mirar el permiso:MODULE_NOT_ENABLEDsi falta el aplicativo, oCAPABILITY_NOT_ENABLEDsi falta la capacidad.
Si tu organización baja de plan, los permisos ya concedidos se conservan: simplemente dejan de funcionar hasta que vuelva el aplicativo. Retirar un permiso es siempre posible, esté o no en plan.
| Familia | Aplicativos del plan | Capacidad |
|---|---|---|
crm:contacts:*, crm:clients:*, crm:budgets:* | CRM | — |
crm:clients:write:hierarchy | CRM | Grupos de empresas |
crm:leads:* | CRM | Leads |
crm:invoices:* | Finanzas | — |
billing:payment-methods:*, billing:charge, billing:refund | Finanzas y Pagos con tarjeta (Stripe) | — |
billing:subscriptions:* | Finanzas | Facturación recurrente |
billing:payment-authorizations:*, billing:scheduled-charges:* | Finanzas y Pagos con tarjeta (Stripe) | Cobro automático |
support:tickets:* | Tickets de soporte | Tickets propios |
fm:files:* | Gestor de archivos | — |
crm:users:*, analytics:* | Integraciones | — |
chat:* | Chat | Agentes de canal, para chat:agents:* |
billing:charge no declara la capacidad de cobro automático porque
también sirve para cobrar con el usuario delante, que funciona sin
ella. La puerta del cobro automático está en el endpoint que la
necesita (/invoices/:id/charge).
Registro de auditoría
Cada cambio queda en el registro de auditoría de tu organización: qué permisos había antes y después, quién los cambió, el motivo si lo dio y si se hizo desde el panel o desde un asistente de IA. Ese registro no se puede modificar.
Automatizar por MCP
La operación equivalente es apps_update_scopes de la herramienta MCP
integrations (exige confirm: true). Sus parámetros y un ejemplo
están en la referencia MCP.
Códigos de error
| Código | HTTP | Cuándo aparece |
|---|---|---|
INVALID_SCOPE | 400 | La lista scopes contiene un valor que no está en el catálogo. |
EXTERNAL_APP_NOT_FOUND | 404 | La aplicación no existe en tu organización. |
EXTERNAL_APP_REVOKED | 409 | La aplicación está desactivada. Reactívala antes de cambiar sus permisos. |
EXTERNAL_APP_SCOPES_CONFLICT | 409 | Bloqueo optimista: otra persona la cambió antes. Recarga y vuelve a intentarlo. |
SUPER_ADMIN_REQUIRED_FOR_RGPD_SCOPE | 403 | Hace falta ser Super Administrador para añadir un permiso protegido. |
REASON_REQUIRED_FOR_RGPD_SCOPE | 422 | Falta reason, o tiene menos de 20 caracteres, al añadir un permiso protegido. |
SCOPE_OUT_OF_PLAN | 400 | El plan de tu organización no cubre ese permiso. Retirarlo siempre es posible. |
SCOPE_NOT_ALLOWED_WITH_ALLOWED_ORIGINS | 400 | La clave de la aplicación está publicada en páginas web y ese permiso no se usa con ella. notAllowedScopes dice cuáles. |
RESPONSIBLE_SELF_ONLY | 403 | Ampliar los permisos solo lo puede hacer la persona responsable de la aplicación o un Super Administrador. |
SCOPE_NOT_ALLOWED_FROM_BROWSER | 403 | La aplicación llamó desde un navegador a una ruta cuyo permiso no se usa en una página. notAllowedScopes dice cuál. |
INSUFFICIENT_SCOPE | 403 | La aplicación llamó a un endpoint sin tener el permiso. requiredScopes dice cuál falta. |
MODULE_NOT_ENABLED | 403 | El plan no incluye el aplicativo del endpoint. Se comprueba antes que el permiso; la respuesta trae su moduleKey. |
CAPABILITY_NOT_ENABLED | 403 | El aplicativo está contratado, pero no la capacidad concreta. La respuesta trae su capabilityKey. |
Cambios del catálogo que afectan a aplicaciones existentes
- 25 de mayo de 2026: los endpoints de facturación, cobros, archivos, tickets, usuarios, presupuestos, analítica de IA y errores pasaron a exigir permiso propio, y se retiró
fm:files:delete(nunca hubo endpoint de borrado). - 5 de julio de 2026: llegó
crm:clients:write:hierarchypara los grupos de empresas. Se exige además decrm:clients:write, y las aplicaciones existentes no lo recibieron solas. - 12 de julio de 2026: llegaron los nueve permisos del chat.
- 5 de septiembre de 2026:
POST /external/v1/users/identifypasó a exigircrm:users:write. - 21 de octubre de 2026: llegó
crm:users:read:fiscal-data, y sin él el listado de usuarios yidentifydejan de devolver el NIF y la dirección de facturación guardados.billing:scheduled-charges:writepasó a crítico financiero (las aplicaciones que ya lo tenían lo conservan) y es el que exige reintentar el cobro de una cuota de suscripción. Y una clave publicada en páginas web solo admite los permisos del navegador. - 22 de octubre de 2026: llegó
analytics:errors:managepara resolver, reabrir y silenciar los errores por la API. Las aplicaciones existentes no lo reciben solas.
El historial completo está en Cambios de la API.
Siguiente paso
Ponlo en práctica
Lo encontrarás en Creadas por tu empresa. Para abrirlo, entra con tu cuenta de UTILIA OS.