Crear y gestionar claves de API

Una clave de API deja que un programa de tu empresa (un script, un cuadro de mando, una automatización) trabaje con UTILIA OS sin que nadie inicie sesión. Cada clave actúa en nombre de una persona de tu equipo, con sus permisos y recortada a lo que marques, y todo lo que hace queda a nombre de esa persona en la Auditoría, con el nombre de la clave. Quien programe la conexión tiene los detalles técnicos en Claves de API de la organización.

Antes de empezar

• El permiso «Gestionar las claves de API» para crear, cambiar, renovar y revocar claves. Con «Ver las claves de API» solo las consultas. De partida, el Super Administrador tiene los dos y el Gerente, solo el de ver.
• Integraciones en tu plan. Las claves para enviar leads desde tu web van con el CRM y se explican en API de leads.
• Si tienes la verificación en dos pasos, crear, renovar o ampliar una clave te pide el código.

Dónde está

En Ajustes, Claves de API están todas las claves de tu organización, en una sola lista. Cada una lleva su tipo: Acceso a la API, las de esta guía; Enviar leads, las que crean leads desde tu web o desde un formulario de captación; y Aplicación externa, que aquí solo se consultan, porque se gestionan en la ficha de su aplicación.

Crear una clave

1. Pulsa Nueva clave

   Si tu plan incluye también el CRM, te pregunta para qué la quieres: elige Acceso a la API. La otra opción, Enviar leads desde tu web, crea una clave que solo da de alta leads.

2. Ponle un nombre

   Escribe el Nombre y, si quieres, la Descripción (opcional). Usa el del programa donde la vas a poner: si un día ese programa se pierde, sabrás qué clave revocar.

3. Elige la persona responsable

   La clave actúa en su nombre y con sus permisos. De partida eres tú, y solo un Super Administrador puede elegir a otra persona.

4. Marca los permisos

   Todos los permisos, Solo lectura o Restringido. Con Restringido eliges, módulo a módulo, Sin acceso, Leer o Escribir. Lo explicamos en Qué puede hacer la clave.

5. Decide la caducidad

   Sin caducidad, 30, 90 o 180 días, 1 año o Elegir una fecha. Si le pones fecha, UTILIA OS avisa antes de que llegue. En Opciones avanzadas puedes cambiar el Límite de peticiones por hora: 1.000 de partida, entre 10 y 10.000.

6. Crea la clave y cópiala

   Pulsa Crear la clave. Se muestra entera una sola vez, con ejemplos para probarla desde tu servidor. Cópiala en el programa o en el gestor de contraseñas donde se vaya a guardar y pulsa Ya la he guardado. Después solo verás sus primeros caracteres.

La clave nueva aparece en la lista como Activa y empieza a funcionar en el acto, solo desde un servidor: UTILIA OS la rechaza si llega desde un navegador.

Qué puede hacer la clave

Una clave nunca puede más que su persona responsable: puede lo que tienen en común sus permisos, lo que marcaste en la clave y tu plan. Ve además los mismos datos que esa persona: si ella solo ve los clientes que tiene asignados, la clave también.

Con Restringido solo salen los módulos de tu plan en los que la persona responsable puede hacer algo. Algunos van juntos: dar acceso a Pagos con tarjeta (Stripe) marca también Finanzas: leer, porque sin él no podría hacer nada.

Hay cosas que ninguna clave puede hacer, sea cual sea el modo: administrar el equipo, los permisos, la seguridad, las claves y las integraciones; entrar en el chat, en el portal del cliente o en las solicitudes de privacidad; fichar o pedir ausencias por una persona; y dejar enlaces públicos, invitaciones a personas de fuera o envíos programados que sigan funcionando después de revocarla. La lista completa está en Lo que ninguna clave puede hacer.

En la ficha de cada clave, Permisos efectivos hoy dice lo que puede hacer de verdad en este momento, módulo a módulo.

Estados de una clave

Antes de que caduque

Si le pusiste caducidad a una clave, UTILIA OS avisa dos veces antes de que llegue: 7 días antes y el día antes. Así ninguna clave con fecha deja tus programas sin servicio por sorpresa.

• Quién lo recibe: la persona responsable de la clave y, si es otra, quien la creó, siempre que sigan activas.
• Por dónde: por los canales que cada una tenga activados en Mi perfil › Avisos, necesitas entrar con tu cuenta, dentro de Seguridad, en la fila Caducidad de las claves de API. De fábrica llega en la aplicación y por correo; también puede llegar al móvil y al navegador, o apagarse.
• Adónde lleva: a la ficha de la clave, en esta misma pantalla, con el botón Ver la clave.
• Si la clave se crea con menos de 7 días por delante, el primer aviso sale enseguida. Si cambias la caducidad, los avisos se vuelven a programar para la fecha nueva.
• Si Integraciones no está en tu plan o la persona responsable ya no está activa, no hay avisos, porque la clave tampoco funciona.

Cuando te llegue y el programa siga necesitando la clave, tienes dos caminos:

• Alarga la caducidad. En la ficha de la clave, pulsa Editar, cambia la Caducidad y pulsa Guardar los cambios. Solo pueden hacerlo su persona responsable, si tiene «Gestionar las claves de API», o un Super Administrador, y pide el código a quien tiene la verificación en dos pasos.
• Crea otra clave y cámbiala en tus programas antes de la fecha.

Renovar no sirve para esto: la clave nueva conserva la caducidad de la anterior. Y una clave caducada ya no se puede alargar ni renovar: hay que crear otra.

Renovar una clave

Renueva una clave cuando cambie quien tiene acceso a ella o cuando sospeches que se ha visto donde no debía. Solo pueden renovarla su persona responsable o un Super Administrador, porque renovar entrega la clave nueva.

1. Pulsa Renovar la clave

   Está en el menú de la clave, en la lista, y al pie de su ficha.

2. Elige cuánto sigue valiendo la anterior

   1 día, 7 días (recomendado), 30 días o Deja de valer en el acto. Con días de margen, la clave pasa a En transición y tus programas siguen funcionando mientras les cambias la clave.

3. Copia la clave nueva

   Si tienes la verificación en dos pasos, te pide el código. La nueva se muestra una sola vez, con la fecha hasta la que vale la anterior.

Cuando todos tus programas usen ya la nueva, pulsa Retirar la anterior ya para que deje de valer sin esperar a la fecha. Mientras dura una transición no se puede volver a renovar con margen: retira antes la anterior.

Revocar una clave

Pulsa Revocar en el menú de la clave o al pie de su ficha. Puedes escribir un Motivo (opcional), que queda en la ficha de la clave y en la auditoría. La clave y su anterior, si la hay, dejan de valer en el acto y no se pueden recuperar: si el programa la sigue necesitando, crea otra.

Pueden revocarla quienes tienen «Gestionar las claves de API» y también su persona responsable.

Al dar de baja a alguien

Al desactivar o archivar a una persona, se revocan en el acto las claves de las que es persona responsable. Reactivarla no las devuelve.

Las claves que creó para otra persona siguen funcionando: una clave actúa con los permisos de su responsable, no de quien la creó, así que su marcha no cambia lo que la clave puede hacer. Lo único que cambia es que deja de recibir sus avisos de caducidad.

Antes de dar de baja a alguien, filtra la lista por persona responsable para ver qué claves se van a cortar y qué programas las usan. Si alguno las sigue necesitando, crea otra clave y cámbiala en el programa.

Quién puede hacer qué

Si algo falla

• La clave dice «Sin responsable activo». Su persona responsable ya no puede entrar y la clave no funciona. En su menú, un Super Administrador elige a otra persona con Nombrar a otra persona; el resto puede Ponerla a mi nombre.
• La clave dice «Pausada». Integraciones no está en tu plan. La clave vuelve a funcionar sola cuando el plan lo incluya; mientras tanto puedes revocarla.
• El programa recibe un error de permiso. Abre la ficha de la clave y mira Permisos efectivos hoy. Si el módulo no aparece, la clave no lo incluye: edítala para ampliarla. Si aparece pero falla igual, es la persona responsable quien no tiene ese permiso: se cambia en sus permisos, no en la clave.
• No sale un módulo al marcar los permisos. Solo salen los módulos de tu plan en los que la persona responsable puede hacer algo.
• Funciona desde el servidor pero no desde una web. Es a propósito: UTILIA OS rechaza las claves que llegan desde un navegador.
• No te deja renovar. Comprueba que eres su persona responsable o Super Administrador, que la clave no está caducada (una caducada no se renueva: crea otra) y que no está ya en transición (pulsa antes Retirar la anterior ya).
• Te ha llegado el aviso de que una clave caduca. Pulsa Ver la clave en el aviso para abrir su ficha y alarga la caducidad o crea otra antes de la fecha, como se explica en Antes de que caduque. Si la clave ya no hace falta, déjala caducar o revócala.
• La clave dice «Caducada». Ya no funciona y no se puede alargar ni renovar: crea otra y cámbiala en el programa.
• No te deja alargar la caducidad. Solo lo hacen su persona responsable o un Super Administrador. Con la organización en modo restringido no se puede alargar ni crear otra hasta que se levante.
• Se perdió la clave. No se puede volver a ver. Renuévala y pon la nueva en tu programa.

Siguiente paso

• Claves de API de la organizaciónCómo las usa quien programa la conexión: cabecera, ejemplos, límites y errores.
• AuditoríaTodo lo que hace una clave queda a nombre de su persona responsable.