API de Omniscol — tokens de autenticación

Clave y token: dos objetos distintos

Omniscol distingue dos objetos que no deben confundirse.

Una clave es un objeto persistente, conservado del lado de Omniscol. Reúne:

• un identificador corto, generado aleatoriamente, público: es el que la lista muestra, y viaja en cada token para designar la clave que hay que verificar;
• una etiqueta descriptiva, modificable en cualquier momento;
• una fecha de caducidad opcional, modificable en cualquier momento;
• un secreto aleatorio largo, extraído del lado del servidor, que sirve como clave de firma criptográfica.

El identificador, la etiqueta y la fecha de caducidad son información de administración: el identificador no es más que una referencia pública, no un elemento secreto. El secreto, en cambio, es el único material de firma: generado aleatoriamente al crear la clave, permanece del lado del servidor, no es modificable, y nunca se muestra ni se devuelve — ni al crearla, ni en la lista de claves. Y aunque se filtrara, no bastaría para falsificar un token: la firma lo combina con una sal propia de la cuenta y con un secreto de servidor que, tampoco, salen nunca de Omniscol.

Un token es un JWT (JSON Web Token) autónomo, firmado con el secreto de la clave. Es lo que usted transmite al sistema externo. Su contenido firmado transporta la cuenta afectada, la lista de puntos de acceso autorizados, la clave de la que deriva y su propia fecha de caducidad.

Dicho de otro modo: una clave firma, un token está firmado. Una misma clave puede firmar varios tokens — todos verificables con el mismo secreto, por lo que todos se revocan juntos si la clave desaparece.

Omniscol no almacena el token: lo genera, lo muestra una vez, y luego lo vuelve a verificar en cada llamada reconstruyendo su firma a partir del secreto de la clave (HMAC SHA-256). Ninguna autorización transportada por el token puede por tanto alterarse sin ese secreto.

Crear un token

La pantalla Compartiendo está disponible en Administración → Importar, exportar en las cuentas Premium. La creación se realiza en dos tiempos: primero se crea una clave, y luego se genera un token a partir de esa clave.

1. Crear una clave — indique una etiqueta descriptiva y, si el acceso es temporal, una fecha de caducidad. Su etiqueta y su caducidad siguen siendo modificables después; su secreto de firma, no.
2. Generar un token — seleccione la clave, marque los puntos de acceso autorizados, elija eventualmente una fecha de caducidad propia del token, y luego genere el JWT.

En la generación, Omniscol muestra el token una sola vez. Cópielo inmediatamente en un gestor de secretos: no se volverá a mostrar. La caducidad del token queda inscrita en su contenido firmado: no se modifica a posteriori. Para cambiar esa fecha, genere un nuevo token.

Hay por tanto dos niveles de caducidad, independientes uno del otro:

• caducidad de la clave — modificable desde la lista de claves; cuando se alcanza, todos los tokens derivados de esa clave son rechazados (la llamada falla con un 401);
• caducidad del token — fijada en la generación, inscrita en el JWT, y no modificable después.

Puntos de acceso autorizados

Un token da acceso únicamente a los puntos de acceso marcados en su generación: nunca dé por hecho que cubre toda la API. La lista autorizada se transporta en el token y se verifica en cada llamada; una llamada hacia un punto de acceso no autorizado se rechaza (401).

Más allá de los puntos de acceso individuales, la lista de selección ofrece atajos por módulo:

• la entrada de un módulo por sí sola autoriza todos sus puntos de acceso;
• las variantes por operación — lectura, modificación, creación, eliminación — restringen el módulo a un solo tipo de llamada.

Marcar «Horario [lectura]» concede así toda la lectura de los horarios sin abrir la más mínima escritura, sin marcar cada punto de acceso uno por uno. Manténgase en lo más ajustado: conceda únicamente los módulos y las operaciones estrictamente necesarios para la integración.

Utilizar un token

Dos maneras habituales de enviar el token a la API:

• Cabecera HTTP: Authorization: Bearer <token> (recomendado).
• Query string: ?auth=<token> (práctico para la depuración, pero aparece en los logs HTTP — a evitar en producción).

Ejemplo curl, a adaptar con un punto de acceso real procedente de la OpenAPI:

curl -H "Authorization: Bearer $TOKEN" \
  https://su-escuela.omniscol.com/api/<module>/<punto-acceso>

Documentación OpenAPI

La pantalla Importar, exportar muestra un enlace OpenAPI 3.1 que abre la especificación disponible para la cuenta en Swagger Editor. Allí encontrará:

• la lista de los puntos de acceso API expuestos,
• los esquemas de los datos intercambiados,
• los métodos y parámetros,
• las respuestas esperadas.

La especificación también la sirve directamente su cuenta, sin autenticación:

• /api/guest/openapi.json — especificación en formato JSON;
• /api/guest/openapi.yaml (o /api/guest/openapi?yaml=true) — mismo contenido en formato YAML;
• /api/guest/school_schema.json — esquema JSON de los datos de la cuenta.

La ayuda completa para su asistente de IA

El portal también publica toda la ayuda de Omniscol en un único archivo de texto, listo para servir de base de conocimientos a un asistente de IA (proyecto Claude, GPT personalizado…):

• omniscol.com/es/llms-full.txt — la guía completa en Markdown, disponible en cada idioma de la ayuda (/en/llms-full.txt, /fr/llms-full.txt…);
• omniscol.com/llms.txt — el índice según el estándar llms.txt, descubierto automáticamente por los motores de IA.

Revocar un acceso

La revocación se realiza a nivel de la clave, no del token individual.

La pantalla enumera las claves que han servido para generar tokens. Eliminar una clave borra su secreto de firma del lado de Omniscol: a partir de entonces, ninguna firma derivada de ese secreto puede seguir verificándose, y toda llamada que presente un token procedente de esa clave falla con un 401. Es la ausencia del secreto lo que invalida los tokens, no una lista de revocación.

Para el departamento de informática, dos consecuencias:

• No hay revocación token por token. Omniscol no conserva los JWT emitidos y no puede desactivar uno de forma aislada: un token ya generado sigue siendo válido hasta su propia caducidad, o hasta que su clave sea eliminada o caduque.
• Modificar la caducidad de una clave actúa inmediatamente sobre todos sus tokens: adelantar esa fecha corta el acceso del conjunto de tokens procedentes de la clave.

Buena práctica: elimine sin esperar toda clave cuya fuga sospeche, y luego recree una clave de reemplazo con una etiqueta descriptiva.

Una clave por destino y por uso

Puesto que la revocación es por clave, dedique una clave a cada integración (un software externo = una clave). El secreto de una clave solo firma sus propios tokens: eliminar esa clave solo invalida los accesos de la integración afectada, sin tocar a los demás.

A la inversa, una clave única compartida entre varios sistemas vuelve toda revocación brutal: eliminar la clave comprometida corta de golpe todos los sistemas que la utilizaban.

Para qué integraciones

La API se utiliza normalmente para:

• sistemas de señalización a medida (más allá de los paneles de información nativos de Omniscol; véase Personalización de los paneles),
• paneles de control externos que consolidan Omniscol y otras fuentes,
• conectores o sincronizaciones con un ERP o un SI de gestión,
• agentes de IA compatibles con MCP que consumen Omniscol vía el servidor MCP; véase MCP — conectar un agente de IA externo.

Para un acceso delegado a un servicio de terceros identificado (token con alcance, consentimiento del usuario, revocable desactivando el cliente), prefiera el servidor OAuth2 de Omniscol: véase OAuth2 / OIDC (proveedor).