Permisos de una clave

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:

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:

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.

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

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 permisosQué permisos tiene cada rol de partida y cómo se ajustan por persona.