API de organización

La API de organización es la interfaz programática de tu propio colegio: los mismos recursos que administras en la consola —padrón, consentimientos, derechos ARCO, RAT, transparencia— disponibles para tus scripts e integraciones internas mediante una API key de organización. En esta página verás cómo se emite una key, cómo se autentica una llamada, qué permisos puede portar y cómo esos permisos determinan cuánto ve del padrón.

El modelo de la API key

Una API key de organización es una credencial emitida por un administrador desde la consola (Integraciones → API keys) o mediante la ruta POST /api/api-keys con sesión activa. Al emitirla se eligen sus permisos con casillas de verificación: la key sólo puede portar permisos del catálogo asignable (listado más abajo) y nunca hereda los permisos de la persona que la creó.

Tres propiedades definen su comportamiento:

• Se muestra una sola vez. La respuesta de creación es la única copia en texto plano; Edugoverna almacena sólo el hash. En adelante la consola muestra el prefix y el inicio enmascarado (start) para identificarla. Si se pierde, se revoca y se emite otra.
• Pertenece a la organización, no a una persona. La key queda ligada al colegio que la emitió (referenceId) y toda llamada opera dentro de ese tenant. No hay que pasar el identificador de la organización en la URL: la key es el contexto.
• Es revocable y auditable. Emitirla y revocarla escribe eventos de auditoría; revocar la deshabilita (queda visible como «Revocada») en vez de borrarla.

Autenticación con x-api-key

Toda llamada lleva la key en el encabezado x-api-key, contra la base https://app.edugoverna.com/api:

curl "https://app.edugoverna.com/api/schools/current" \
  -H "x-api-key: {tu_api_key}"

Casi todas las rutas de la API de organización aceptan indistintamente una sesión de la consola (cookie) o una API key: si no hay sesión y falta el encabezado, la respuesta es 401 API_KEY_REQUIRED. Una key deshabilitada o expirada responde 401. Unas pocas rutas pensadas para sistemas (como las verificaciones de /records) exigen API key incluso con sesión activa, y las operaciones sensibles marcadas «sólo sesión» en estas páginas rechazan cualquier key.

Algunas superficies sensibles son sólo de sesión: exportaciones ARCO, incidentes de seguridad, reporte al regulador, decisiones manuales de consentimiento con evidencia, y la purga de titulares, entre otras. Cada página de esta referencia lo indica donde corresponde con la frase «sólo disponible con sesión de la consola». Un intento con API key sobre esas superficies queda además registrado en auditoría.

Permisos asignables

Estos son los 28 permisos que una API key de organización puede portar, agrupados por familia. En cada endpoint de esta referencia encontrarás cuál exige.

La escalera de lectura de titulares

Los cinco permisos subjects.read.* no son excluyentes entre sí: componen una proyección que determina qué campos de cada titular devuelve la API. La identidad y el contacto se resuelven por separado, y la key puede combinar tiers (por ejemplo identity_basic + contact_masked).

Dos reglas transversales protegen el padrón independiente del tier:

1. Los listados nunca son sensibles. GET /data-subjects degrada la proyección a nivel de nómina (identity_sensitive → basic, contact_full → masked). El registro completo con PII sólo existe en el detalle (GET /data-subjects/:subjectId), y leerlo con proyección sensible queda registrado.
2. Buscar por nombre exige poder leer uno. El parámetro de búsqueda sólo consulta nombres si la proyección es al menos identity_basic; a tier directory la búsqueda por RUT o correo funciona como verificación de pertenencia, pero se audita sin almacenar el término.

El detalle está en Sujetos del padrón.

Listar las API keys

curl "https://app.edugoverna.com/api/api-keys" \
  -H "Cookie: {sesion_de_consola}"

{
  "apiKeys": [
    {
      "id": "k4d9…",
      "name": "Sync biblioteca",
      "start": "edug_a1b2",
      "prefix": "edug",
      "enabled": true,
      "permissions": [
        "students.read",
        "subjects.read.contact_masked",
        "subjects.read.identity_basic"
      ],
      "expiresAt": null,
      "lastRequest": "2026-08-24T18:12:03.000Z",
      "requestCount": 1204,
      "metadata": null,
      "createdAt": "2026-06-01T12:00:00.000Z",
      "updatedAt": "2026-08-24T18:12:03.000Z"
    }
  ],
  "total": 1
}

Emitir una API key

curl -X POST "https://app.edugoverna.com/api/api-keys" \
  -H "Cookie: {sesion_de_consola}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sync biblioteca",
    "prefix": "edug",
    "permissions": [
      "students.read",
      "subjects.read.identity_basic",
      "subjects.read.contact_masked"
    ]
  }'

{
  "id": "k4d9…",
  "name": "Sync biblioteca",
  "key": "edug_a1b2c3d4e5…",
  "start": "edug_a1b2",
  "prefix": "edug",
  "enabled": true,
  "permissions": [
    "students.read",
    "subjects.read.contact_masked",
    "subjects.read.identity_basic"
  ],
  "expiresAt": null,
  "createdAt": "2026-08-25T12:00:00.000Z",
  "updatedAt": "2026-08-25T12:00:00.000Z"
}

Revocar una API key

curl -X DELETE "https://app.edugoverna.com/api/api-keys/k4d9…" \
  -H "Cookie: {sesion_de_consola}"

Errores y límites

Todos los errores llegan en el mismo sobre, con un código estable y un mensaje en español:

{
  "error": {
    "code": "SUBJECTS_READ_FORBIDDEN",
    "message": "Se requiere un permiso de lectura de titulares…",
    "details": null
  }
}

Cada key trae un límite de tasa propio (por defecto 10.000 solicitudes por ventana de 24 horas); al excederlo la verificación de la key deja de aceptarla y la API responde 401 con el código RATE_LIMITED hasta que la ventana se renueva. El catálogo de códigos está en Errores y la política completa de límites en Límites.

Las páginas de esta referencia

• Sujetos del padrón — titulares, apoderados, Generaciones y Cursos.
• Consentimientos — campañas, solicitudes y evidencia.
• Derechos ARCO — solicitudes de derechos y portal ARCO.
• Actividades de tratamiento — RAT y evaluaciones de impacto.
• Riesgos — catálogo, medidas y registro de riesgos.
• Importaciones — el importador de planillas.
• Transparencia — portal público, marca y dominios.
• Gobernanza y evidencia — encargados, capacitaciones, reportes.