Usuarios API #

Un usuario API es la cuenta con la que un sistema externo se conecta a la plataforma del colegio de forma automática, con una contraseña propia, una lista cerrada de endpoints autorizados y un alcance de grupos definido. Este artículo cubre el alta, la modificación, la desactivación y la reactivación de esos usuarios.

IMPORTANTE: Crear, modificar, desactivar y reactivar un usuario API es exclusivo del administrador principal de la plataforma (la cuenta ADMIN001). Los administradores del colegio entran a Usuarios API y ven la lista y el detalle de cada usuario, pero no ven las pestañas Agregar usuario API, Modificar, Desactivar ni Reactivar, y tampoco existe un permiso de operador que las habilite. Lo que el colegio sí consulta está documentado en Usuarios API.

1. Desde el Panel de control entra a Usuarios API.
2. Selecciona la pestaña Agregar usuario API.
3. En el panel Agregar usuario API, del lado izquierdo, captura los datos de la cuenta:
   • Nombre: Obligatorio. Identifica al sistema o a la persona responsable de la integración. No puede exceder 64 caracteres.
   • Apellido paterno: Obligatorio. No puede exceder 64 caracteres.
   • Apellido materno: Opcional. No puede exceder 64 caracteres.
   • Nombre de usuario: Obligatorio. Solo admite caracteres alfanuméricos y no puede exceder 32 caracteres. El icono Revisar disponibilidad comprueba que no esté ocupado y el icono Generar nombre de usuario propone uno automáticamente.
   • Correo electrónico: Opcional. No puede exceder 64 caracteres. Si el dominio que escribes se parece a uno conocido, la plataforma te pregunta “¿Quisiste decir @@suggestion@@ en vez de @@original@@?” y puedes responder Sí, corregir o No, así está bien.
   • Fecha de nacimiento: Opcional. Se elige en el calendario; el campo no se escribe a mano.
   • Contraseña: Viene generada por la plataforma y no se puede editar. El icono Copiar al portapapeles la copia —verás el aviso “Contraseña copiada al portapapeles.”— y el icono Contraseña nueva genera otra. Cópiala antes de guardar: después del alta ya no vuelve a mostrarse.
   • Direcciones IPv4 y CIDR: Obligatorio. Escribe una dirección y presiona Enter para agregarla; cada una queda como una etiqueta morada que puedes quitar con su icono de tache. Se acepta la dirección sola o con máscara CIDR. Si dejas el campo vacío, al guardar se muestra “Es necesario agregar una o mas direcciones IPv4”; si alguna etiqueta no tiene forma válida, “Dirección IPv4 inválida”.
   • Direcciones IPv6 y CIDR: Opcional, y funciona igual que el anterior. Una etiqueta mal formada produce “Dirección IPv6 inválida”.
4. En la columna Endpoints marca los endpoints a los que el usuario tendrá acceso. Están organizados en grupos y subgrupos: la casilla del encabezado Endpoints marca y desmarca la columna entera, la de un grupo marca todo su contenido y la de un subgrupo, el suyo. Al final de cada ruta se listan los métodos disponibles, cada uno con su propia casilla.
5. La columna Endpoints internos funciona igual y contiene los endpoints reservados a la operación de Algebraix. No se muestra a nadie más.
6. Si la lista es larga, usa el campo Filtrar permisos que está arriba de las columnas: al escribir, ambas columnas se acotan a lo que coincide.
7. Debajo de las columnas está el apartado Permisos de grupo, donde defines a qué grupos alcanza el usuario API:
   • La casilla Acceso a todos los grupos (actuales y futuros) le da acceso a todos los grupos, incluidos los que se creen después; al marcarla se oculta el selector de grupos y ya no tienes que elegir nada más.
   • Si prefieres acotarlo, desmárcala y elige los grupos en el selector, organizado por campus, sección y grado. La casilla Seleccionar todo marca y desmarca todos los grupos de una vez, y los que vas marcando se enlistan a la derecha bajo Grupos seleccionados.
   • En Búsqueda por grupo escribe parte del nombre de un grupo para acotar el árbol; Limpiar quita el filtro.
   • Si el colegio usa perfiles de grupo, el menú Perfiles marca de una vez los grupos que forman el perfil que elijas y desmarca lo que tuvieras seleccionado; la opción Ninguno deja todo sin marcar.
8. Para guardar da clic en Aceptar. Verás el mensaje “Usuario API creado” y el usuario aparecerá en la pestaña Usuarios API.
9. IMPORTANTE: No se puede guardar un usuario API sin endpoints ni sin grupos: si falta alguno se muestra “Es necesario seleccionar al menos un permiso para el usuario API” o “Es necesario seleccionar al menos un grupo”.

1. Desde el Panel de control entra a Usuarios API y da clic en el nombre de usuario que quieres modificar.
2. Selecciona la pestaña Modificar.
3. Se muestra el panel Modificar usuario API con los datos ya capturados. Aquí solo puedes cambiar Nombre, Apellido paterno, Apellido materno, Correo electrónico, la contraseña y las direcciones IP: el Nombre de usuario y la Fecha de nacimiento no se editan desde esta pantalla.
   • Nombre y Apellido paterno siguen siendo obligatorios y ninguno de los campos de texto puede exceder 64 caracteres.
   • La Contraseña aparece enmascarada. Para cambiarla da clic en el icono Contraseña nueva : se abre el aviso “Cambiar contraseña” con el texto “Al actualizar la contraseña, tendrás que generar un nuevo token.” y, al confirmar con Actualizar, se genera una contraseña nueva y aparece el icono Copiar al portapapeles para copiarla. Cópiala en ese momento: al salir de la pantalla ya no se muestra.
   • Las Direcciones IPv4 y CIDR y las Direcciones IPv6 y CIDR ya registradas se muestran como etiquetas; puedes quitarlas con su icono de tache y agregar nuevas. La lista de IPv4 no puede quedar vacía.
4. Las columnas Endpoints y Endpoints internos llegan con lo que el usuario ya tiene marcado; márcalas o desmárcalas igual que en el alta, con el campo Filtrar permisos para acotar la lista.
5. En Permisos de grupo se conserva el alcance actual: la casilla Acceso a todos los grupos (actuales y futuros) viene marcada si el usuario lo tiene, y si no, el selector viene con sus grupos ya seleccionados. Si alguno de sus grupos está inactivo, el selector los incluye desde el principio.
6. Para guardar da clic en Aceptar. Verás el mensaje “Usuario API actualizado”.
7. Nota: Si el usuario está desactivado, la pantalla solo muestra el aviso “Usuario desactivado” y no se puede modificar; primero hay que reactivarlo.

Al desactivar un usuario API la plataforma libera su nombre de usuario, borra sus direcciones IP autorizadas y le quita todos sus endpoints y todos sus grupos. La integración que usaba esa cuenta deja de funcionar de inmediato y, si después se reactiva, hay que volver a asignarle todo. Por eso conviene avisar al colegio antes de hacerlo.

1. Desde el Panel de control entra a Usuarios API y da clic en el nombre de usuario que quieres desactivar.
2. Selecciona la pestaña Desactivar.
3. Se muestra la tarjeta Confirmar desactivación con la pregunta “¿ Está seguro que desea desactivar al usuario API” seguida del nombre de usuario.
4. Da clic en Desactivar. Verás el mensaje “Usuario API desactivado” y regresarás a la lista, donde el usuario ya aparece en el panel Usuarios API desactivados.
5. Nota: La pestaña Desactivar no se ofrece para las cuentas de integración de la propia plataforma, y si el usuario ya estaba desactivado la pantalla solo muestra “El usuario ya ha sido desactivado.”.

Un usuario API desactivado perdió su nombre de usuario, su contraseña, sus endpoints y sus grupos, así que reactivarlo es en la práctica volver a darlo de alta sobre la misma cuenta.

1. Desde el Panel de control entra a Usuarios API.
2. En el panel Usuarios API desactivados da clic en Reactivar, en la columna Acciones del usuario que quieres recuperar. También puedes entrar a su detalle desde su nombre y usar la pestaña Reactivar.
3. Se muestra el panel Reactivar usuario API, con los datos que tenía y el nombre de usuario vacío:
   • Nombre de usuario: Obligatorio. Hay que capturarlo de nuevo porque el anterior se liberó al desactivar. Solo admite caracteres alfanuméricos, no puede exceder 32 caracteres y cuentas con los iconos Revisar disponibilidad y Generar nombre de usuario . Si el nombre ya está ocupado, se muestra “Nombre de usuario no disponible”.
   • Nombre, Apellido paterno, Apellido materno y Correo electrónico: Llegan con lo que tenía y puedes corregirlos. Nombre y Apellido paterno son obligatorios.
   • Contraseña: Se genera una nueva automáticamente. Cópiala con el icono Copiar al portapapeles o genera otra con Contraseña nueva .
4. Da clic en Aceptar. Verás el mensaje “Cuenta de usuario API reactivada. Es necesario modificar al usuario API y asignarle permisos de acceso” y volverás a la lista.
5. IMPORTANTE: La reactivación no devuelve endpoints ni grupos. Entra enseguida a la pestaña Modificar del usuario y vuelve a marcar sus endpoints, sus direcciones IPv4 y su alcance de grupos; mientras no lo hagas, la integración seguirá sin funcionar.

Al entrar como el administrador principal de la plataforma al detalle de un usuario API activo, además de la ficha, el panel Endpoints y el panel Permisos de grupo que ya ve cualquier administrador del colegio (documentados en Usuarios API), se muestra un panel adicional, Endpoints internos, con los endpoints reservados a la operación de Algebraix a los que tiene acceso esa cuenta. Ningún administrador ni operador del colegio ve este panel.

1. El campo Filtrar permisos, arriba de los paneles, acota tanto Endpoints como Endpoints internos conforme escribes.