Autenticación de la API pública: claves, ámbitos y seguridad

La API pública de Studeia expone las rutas /api/institution/* para integraciones. Toda solicitud se autentica por sesión (en la app) o por clave de API (Bearer). Esta guía cubre las claves, los ámbitos y las buenas prácticas.

Respuesta rápida

Autentícate con Bearer token (clave con prefijo mia_)
Las claves se crean en Configuración → API Keys
Ámbitos con el patrón recurso:acción limitan cada clave
La clave completa aparece solo una vez (el servidor guarda solo el hash)
Las operaciones sensibles aceptan solo sesión, nunca API key

Cómo autenticarse

Envía la clave en el header Authorization:

GET /api/institution/courses
Authorization: Bearer mia_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

La doble autenticación (resolveAuth) acepta sesión (en la app) o clave de API (integraciones). Para claves, la respuesta incluye headers de rate limit.

Ámbitos (principio de menor privilegio)

Los ámbitos siguen el patrón recurso:acción. Ejemplos:

Recurso	Lectura	Escritura
Cursos	`courses:read`	`courses:write`
Usuarios	`users:read`	`users:write`
Matrículas	`enrollments:read`	`enrollments:write`
Grupos	`classes:read`	`classes:write`
Informes	`reports:read`	—

Crea claves con el mínimo de ámbitos necesarios. Una clave usada solo para lectura de informes no necesita ámbitos de escritura.

Seguridad de la clave

La clave completa se muestra una única vez en la creación.
El servidor almacena solo el hash SHA-256 — la clave no es recuperable.
Revocar/editar una clave invalida el acceso de inmediato.
En caso de filtración, revócala y genera una nueva.

Rutas que NO aceptan API key

Por seguridad, las operaciones críticas requieren autenticación de sesión (sessionOnly) y nunca aceptan API key:

Gestión de claves de API.
Billing / checkout (evita la automatización de compras).
Moderación del supervisor IA.

Buenas prácticas

Usa menor privilegio en los ámbitos.
Rota las claves periódicamente.
Nunca expongas la clave en el frontend ni en repositorios.
Monitorea el uso (cada solicitud queda registrada).
Gestiona los rate limits (consulta la página dedicada).

Preguntas frecuentes

¿Cómo me autentico? Bearer token con la clave mia_ en el header Authorization.

¿Qué son los ámbitos? Límites recurso:acción de lo que la clave puede hacer.

¿La clave queda visible después? No — solo en la creación; el servidor guarda solo el hash.

¿Sirve para cualquier ruta? Para la mayoría; billing, claves y moderación son solo de sesión.

Consulta la visión general de la API y webhooks y rate limits.

FAQ

¿Cómo autentico una solicitud en la API de Studeia?

Envía la clave de API en el header Authorization como Bearer token. Las claves tienen el prefijo mia_ y se generan en Configuración → API Keys de la institución. Cada solicitud también está sujeta a rate limiting, y el uso se registra para auditoría.

¿Qué son los ámbitos (scopes) y por qué son importantes?

Los ámbitos limitan lo que cada clave puede hacer, con el patrón recurso:acción (ej: courses:read, users:write). Una clave solo ejecuta operaciones cubiertas por sus ámbitos. Crea claves con el mínimo de ámbitos necesarios (principio de menor privilegio) — una clave de lectura no debe tener ámbitos de escritura.

¿La clave de API completa queda visible después de creada?

No. La clave completa se muestra solo una vez, en el momento de la creación. El servidor almacena únicamente un hash (SHA-256), de modo que la clave no puede recuperarse después. Guárdala de forma segura; si la pierdes, revócala y genera una nueva.

¿Puedo usar la API key para cualquier ruta institucional?

Para la mayoría de las rutas /api/institution/*, sí — con el ámbito correcto. Excepciones: las operaciones sensibles (gestión de claves de API, billing/checkout, moderación del supervisor IA) solo aceptan autenticación de sesión (sessionOnly), nunca API key, para evitar la automatización de acciones críticas.