Crear el primer token
1
Identifica la integración, no a la persona
Nombre operativo, responsable, correo de contacto, sistema de origen y ambiente. Un token por sistema y por ambiente: cuando haya que revocar uno, no se cae el resto.
2
Da solo los scopes activos que ese sistema necesita
Si el SIS solo lee estudiantes,
students:read y nada más. Ver Scopes.3
Define expiración, recordatorio de rotación y tope de peticiones
El rate limit es por token y por minuto. Súbelo con criterio, no por defecto.
4
Agrega la IP allowlist si el cliente ya conoce sus salidas
Acepta IPv4 literal o CIDR IPv4. Es la defensa más barata contra un token filtrado.
5
Guarda el token en el gestor de secretos del cliente
Nunca por chat, nunca en un ticket, nunca en el repositorio.
Qué valida el servidor en cada petición
clientApiAuthMiddleware revisa, en este orden, y falla en el primero que no pase:
Permisos del lado de EdTools
Quien administra las keys dentro del dashboard necesita:settings.api.read— ver keys, actividad y catálogo de endpoints.settings.api.manage— crear, editar, rotar y revocar.
Rotar sin cortar el servicio
Rotar emite un token nuevo e invalida el anterior. El orden que no rompe nada:1
Crea una key nueva con los mismos scopes
Dos tokens válidos a la vez es una situación normal y transitoria.
2
Despliega el token nuevo en el sistema externo
Confirma con una llamada a
/me que responde con el apiKey.id nuevo.3
Revoca el viejo
Y revisa la actividad: si algo seguía usándolo, aparecerá como
401 con el nombre de la key.Cuando algo falla
En Ajustes → API e integraciones → Actividad puedes buscar por path, API key, IP, user-agent orequestId. Cada detalle trae el endpoint, el scope exigido, el Source of Record, los módulos requeridos, el código de error y el estado del rate limit — con un resumen copiable que no incluye payloads sensibles ni el header Authorization.
Para pedir soporte a EdTools, manda ese resumen: requestId, nombre de la key, sistema de origen y ventana horaria. Nunca el token.