# Permisos de una clave Qué puede hacer una clave según su modo y su persona responsable, qué módulos se pueden marcar y lo que ninguna clave puede hacer. Una clave nunca puede más que su persona responsable. Lo que puede hacer en cada petición es lo que tienen en común tres cosas: los permisos de esa persona en ese momento, lo que marcaste en la clave y el plan de tu organización. Ve además las mismas filas que la persona: si ella solo ve los clientes que tiene asignados, la clave también. Por eso una clave cambia sin que nadie la toque: si a la persona le quitan un permiso, la clave lo pierde en la petición siguiente; si el plan deja de incluir un módulo, la clave deja de llegar a él. ## Los tres modos Al crear la clave eliges uno de tres modos, que viajan en `permissionMode`: **Tres formas de recortar una clave** ### Todos los permisos (ALL) Lo que pueda hacer la persona en cada momento, salvo lo que ninguna clave puede hacer. Si la persona gana un permiso, la clave también lo gana. ### Solo lectura (READ_ONLY) Consulta todo lo que la persona puede ver. Una petición que cambia algo responde 403. ### Restringido (RESTRICTED) Solo los módulos que marques en moduleAccess, cada uno con leer o escribir. Escribir incluye leer. Con **Solo lectura**, las consultas que se piden con `POST`, como algunas búsquedas y vistas previas, sí funcionan: lo que cuenta es si la ruta cambia algo, no el método. Con **Restringido**, cada módulo va en `moduleAccess` como `modulo:read` o `modulo:write`, por ejemplo `["crm:write", "finance:read"]`. En los otros dos modos, `moduleAccess` va vacío. ## Módulos que se pueden marcar En la pantalla solo salen los módulos que incluye tu plan y en los que la persona responsable puede hacer algo: | Módulo | En `moduleAccess` | Qué se puede marcar | | - | - | - | | CRM | `crm` | Leer o escribir | | Finanzas | `finance` | Leer o escribir | | Pagos con tarjeta (Stripe) | `stripe` | Leer o escribir. Exige también «Finanzas: leer» | | Gestión de proyectos | `work` | Leer o escribir | | Tickets de soporte | `support` | Leer o escribir | | Calendario | `calendar` | Leer o escribir | | Gestor de archivos | `files` | Leer o escribir | | Marketing | `marketing` | Leer o escribir | | AI Studio | `ai-studio` | Leer o escribir | | Meet | `meet` | Leer o escribir | | Call Copilot | `call-copilot` | Leer o escribir | | RRHH | `attendance` | Leer o escribir | | Formación | `training` | Leer o escribir | | Scraper | `scraper` | Leer o escribir | | Gamificación | `gamification` | Leer o escribir | | Anuncios | `announcements` | Leer o escribir | | Equipo | `team` | Solo leer: las personas y los departamentos, para saber a quién asignar algo | Si un módulo sale del plan, lo marcado no se borra: deja de tener efecto y vuelve a tenerlo cuando el plan lo incluya. Lo que está en «Próximamente» sigue cerrado para cualquier clave. La ficha de la clave (`GET /api/v2/organization-api-keys/:id`, con sesión) y la propia clave (`GET /api/v2/organization-api-keys/current`) devuelven `effectivePermissions`: lo que puede hacer hoy en cada módulo, ya cruzado con la persona y el plan. Es lo primero que mirar cuando una petición responde `403`. Su diagnóstico (`GET /api/v2/organization-api-keys/current/diagnostics`) da además la lista de permisos de cada módulo, los módulos marcados que el plan ya no incluye y las llamadas rechazadas con su código: lo explica [Comprobar una clave](https://os.utilia.ai/docs/developers/organization-api-keys/diagnostics). ## Lo que ninguna clave puede hacer Una clave trabaja sin nadie delante y puede filtrarse, así que hay cosas que se reservan a una persona con su sesión, sea cual sea el modo: - **Gobernar la organización**: las personas, los roles y los permisos, la seguridad, las sesiones, la verificación en dos pasos, los datos de la organización y el plan. De Ajustes, una clave solo consulta las personas y los departamentos. - **Crear otros accesos**: claves, aplicaciones externas, clientes OAuth, conexiones MCP, avisos a servidores externos y contraseñas de aplicación de la unidad de red. Tampoco conecta un buzón de correo. - **Entrar en áreas privadas**: el chat, el portal del cliente y sus invitaciones, las solicitudes de privacidad, la bandeja personal de avisos y la presencia del equipo. - **Dejar algo que siga funcionando después de revocarla**: - enlaces públicos: compartir un archivo o un documento, enviar un presupuesto (lleva su enlace para verlo y firmarlo) o compartirlo con otro correo, y los enlaces públicos de una factura o de una autorización de cobro; - invitar a personas de fuera a una reunión o a un evento; - programar informes, campañas o recordatorios para más tarde; - crear o cambiar formularios de captación y automatizaciones. - **Actos personales**: fichar, registrar pausas, generar el código de fichaje, pedir ausencias propias, entrar en una reunión o grabarla. - **Lo que tiene efecto legal o mueve credenciales de cobro**: el certificado digital y la configuración de VeriFactu, y conectar o cambiar la cuenta de cobro con tarjeta. - **Acciones que piden la verificación en dos pasos**, como exportar todos los datos de la organización: responden `403 API_KEY_ACTION_REQUIRES_SESSION`. - **Conexiones en tiempo real**: los eventos en tiempo real (`403 API_KEY_STREAMING_NOT_AVAILABLE`) y los WebSocket. Si tu servidor necesita enterarse de los cambios al momento, usa los [avisos a tu servidor](https://os.utilia.ai/docs/developers/webhooks/overview) de una aplicación externa. La clave tampoco abre las otras puertas: la API externa (`/api/external/v1`), la API de leads (`/api/v1/leads`) y los servidores MCP responden `401` con ella. ## Si una petición responde 403 Hay dos errores de permiso que se parecen mucho y se arreglan en sitios distintos: **Dos errores de permiso que se confunden** ### La clave no lo incluye (API_KEY_PERMISSION_NOT_GRANTED) Lo que marcaste al crearla no llega a esa ruta. Se arregla ampliando la clave o usando otra que lo tenga. ### La persona no lo tiene (API_KEY_RESPONSIBLE_PERMISSION_MISSING) La clave lo incluye, pero su persona responsable no tiene ese permiso. Se arregla en sus permisos, no en la clave. Los dos traen en `permissions` la lista de permisos que faltan. Ampliar una clave solo lo hacen su persona responsable, si tiene «Gestionar las claves de API», o un Super Administrador, con la verificación en dos pasos si la tienen activa. Si el error es `API_KEY_ROUTE_NOT_AVAILABLE`, la ruta queda fuera de cualquier clave y no hay permiso que la abra: hazlo desde UTILIA OS. ## Siguiente paso - [Roles y permisos](https://os.utilia.ai/docs/guides/concepts/roles-and-permissions): Qué permisos tiene cada rol de partida y cómo se ajustan por persona.